{
  "openapi": "3.1.0",
  "info": {
    "title": "StellarFirm public API",
    "version": "1.1.0",
    "summary": "The routes of StellarFirm that a person or an agent can call.",
    "description": "StellarFirm gives you AI Agents, Agentic Assistants for your work that you run as the CEO. API-Version: 1 selects major version 1; omitting it selects version 1. Breaking changes require a new major version. Deprecation and Sunset headers announce retirement at least 90 days ahead; see https://stellarfirm.ai/docs/api/policy. This is the small public HTTP API of the web app. Every route answers JSON, and every failure answers the same `ApiError` shape with a stable `error.code`. Authentication is described at https://stellarfirm.ai/docs/api/authentication, the routes with examples at https://stellarfirm.ai/docs/api/endpoints, and every error code at https://stellarfirm.ai/docs/api/errors.",
    "contact": {
      "name": "StellarFirm",
      "email": "hey@stellarfirm.ai",
      "url": "https://stellarfirm.ai/support"
    },
    "termsOfService": "https://stellarfirm.ai/terms"
  },
  "externalDocs": {
    "description": "StellarFirm API docs",
    "url": "https://stellarfirm.ai/docs/api"
  },
  "servers": [
    {
      "url": "https://stellarfirm.ai",
      "description": "StellarFirm"
    }
  ],
  "tags": [
    {
      "name": "Status",
      "description": "Is the site up, and is there a notice."
    },
    {
      "name": "Account",
      "description": "The signed-in account: access and credits."
    },
    {
      "name": "Email",
      "description": "Links that arrive in an email."
    },
    {
      "name": "Free trial",
      "description": "A few free prompts for a visitor with no account, from the landing page."
    },
    {
      "name": "Marketplace",
      "description": "Pay one public assistant for one task, with no account. Test networks only."
    }
  ],
  "paths": {
    "/a2a/a2a-demo/x402": {
      "post": {
        "operationId": "payDemoExpertX402",
        "tags": [
          "Marketplace"
        ],
        "summary": "Send the demo expert a task, paid with x402",
        "description": "Send `{ \"text\": \"...\" }` and the demo expert counts the words and returns a SHA-256 of the text. The first request answers 402 with the payment request. Pay it with an x402 client, on the Base Sepolia test network and send the same request again with the payment attached. Test networks only; nothing real is charged.",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "The public API major version. Omit it for version 1. An unsupported value returns 400. See https://stellarfirm.ai/docs/api/policy.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          }
        ],
        "security": [],
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.01"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 20000,
                    "description": "The text to count and hash."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task ran. The answer is in the task's artifacts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "The API-Version header is unsupported. Send 1 or omit it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Payment required. Pay the request and send it again.",
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/a2a/a2a-demo/mpp": {
      "post": {
        "operationId": "payDemoExpertMpp",
        "tags": [
          "Marketplace"
        ],
        "summary": "Send the demo expert a task, paid with MPP",
        "description": "Send `{ \"text\": \"...\" }` and the demo expert counts the words and returns a SHA-256 of the text. The first request answers 402 with the payment request. Pay it with an MPP client, on the Tempo test network and send the same request again with the payment attached. Test networks only; nothing real is charged.",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "The public API major version. Omit it for version 1. An unsupported value returns 400. See https://stellarfirm.ai/docs/api/policy.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          }
        ],
        "security": [],
        "x-payment-info": {
          "protocols": [
            "mpp"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.01"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 20000,
                    "description": "The text to count and hash."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task ran. The answer is in the task's artifacts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "The API-Version header is unsupported. Send 1 or omit it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Payment required. Pay the request and send it again.",
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Status"
        ],
        "summary": "Check that the web app is up",
        "description": "Answers `ok: true` while the web app is running. It needs no sign-in and reads nothing from an account. Use it for an uptime check.",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "The public API major version. Omit it for version 1. An unsupported value returns 400. See https://stellarfirm.ai/docs/api/policy.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "The web app is running.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/Health"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF draft quota remaining; t is seconds until retry on refusal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft quota policy with q requests and w seconds.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility field: requests allowed per window.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility field: requests left for this caller.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          },
          "400": {
            "description": "The API-Version header is unsupported. Send 1 or omit it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF draft quota remaining; t is seconds until retry on refusal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft quota policy with q requests and w seconds.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility field: requests allowed per window.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility field: requests left for this caller.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "description": "Too many health checks from this address. Wait for Retry-After seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF draft quota remaining; t is seconds until retry on refusal.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft quota policy with q requests and w seconds.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility field: requests allowed per window.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility field: requests left for this caller.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "Retry-After": {
                "description": "Seconds before trying again.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/api/site-banner": {
      "get": {
        "operationId": "getSiteBanner",
        "tags": [
          "Status"
        ],
        "summary": "Read the announcement strip",
        "description": "The notice shown at the top of the site, or `banner: null` when there is none. It is the same for everyone, needs no sign-in, and may be cached for half a minute. Browsers on other origins may read it.",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "The public API major version. Omit it for version 1. An unsupported value returns 400. See https://stellarfirm.ai/docs/api/policy.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "The current notice, or null.",
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "Shared caches may keep the answer briefly.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/SiteBannerResponse"
                }
              }
            }
          },
          "400": {
            "description": "The API-Version header is unsupported. Send 1 or omit it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/api/entitlement": {
      "get": {
        "operationId": "getEntitlement",
        "tags": [
          "Account"
        ],
        "summary": "Check whether the signed-in account may run",
        "description": "Answers whether the signed-in account may run: an active trial, a licence, or free Hobby after the trial. The desktop app asks this before it runs, and an agent acting for an account can ask it too. Only a `200` with `ok: true` means the account may run. It is never cached.",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "The public API major version. Omit it for version 1. An unsupported value returns 400. See https://stellarfirm.ai/docs/api/policy.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The account may run (trial, licence or Hobby). Ask again within `recheckAfterSeconds`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/EntitlementAllowed"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "The API-Version header is unsupported. Send 1 or omit it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "No signed-in session. `status` is `signed-out` and `error.code` is `signed_out`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/EntitlementDenied"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "The account is signed in but may not run: its trial record could not be read (`invalid`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/EntitlementDenied"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "503": {
            "description": "Sign-in is not set up here (`unconfigured`) or the account could not be checked (`unavailable`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/EntitlementDenied"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/credits/balance": {
      "get": {
        "operationId": "getCreditsBalance",
        "tags": [
          "Account"
        ],
        "summary": "Read the account's credit balance",
        "description": "The signed-in account's balance as a count of StellarFirm credits. It is a number of credits and nothing else. It is never cached.",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "The public API major version. Omit it for version 1. An unsupported value returns 400. See https://stellarfirm.ai/docs/api/policy.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The balance, in credits.",
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "Private and never stored.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/CreditsBalance"
                }
              }
            }
          },
          "400": {
            "description": "The API-Version header is unsupported. Send 1 or omit it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "No signed-in session. The `error.code` is `signed_out`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "503": {
            "description": "The answer could not be read right now. Try again shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/email/unsubscribe": {
      "post": {
        "operationId": "unsubscribeFromOnboardingEmails",
        "tags": [
          "Email"
        ],
        "summary": "Stop the later onboarding emails",
        "description": "One-click unsubscribe from the onboarding emails (RFC 8058). The signed `token` in the link is the credential, so no sign-in is needed. Use the link exactly as it was sent.",
        "security": [],
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "The public API major version. Omit it for version 1. An unsupported value returns 400. See https://stellarfirm.ai/docs/api/policy.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": true,
            "description": "The signed token from the link in the email.",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The later emails are stopped.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "You will not get the later onboarding notes."
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "The token is missing or not valid. The `error.code` is `invalid_token`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "502": {
            "description": "The later emails are still scheduled. The `error.code` is `upstream_failed`. Try the link again.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/try/status": {
      "get": {
        "operationId": "getTrialStatus",
        "tags": [
          "Free trial"
        ],
        "summary": "Read the free trial's status",
        "description": "Says whether this month's free trial is still open and how many free prompts the visitor has left. The visitor is told apart by network address, with no sign-in and no cookie. It counts nothing and is never cached. It answers `404` with the code `not_found` while the free trial is switched off.",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "The public API major version. Omit it for version 1. An unsupported value returns 400. See https://stellarfirm.ai/docs/api/policy.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "The trial's status for this visitor.",
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The answer is never cached.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/TrialStatus"
                }
              }
            }
          },
          "400": {
            "description": "The API-Version header is unsupported. Send 1 or omit it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "The free trial is switched off. The `error.code` is `not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "503": {
            "description": "The status could not be read right now. The `error.code` is `unavailable`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/try/prompt": {
      "post": {
        "operationId": "sendTrialPrompt",
        "tags": [
          "Free trial"
        ],
        "summary": "Send one free prompt",
        "description": "Sends one prompt to one of three assistants (`coder`, `marketing` or `product-owner`) and answers with its work. Each visitor gets a few prompts, one at a time, and the whole trial has an allowance for the month. Send `Accept: text/event-stream` to read the work as it happens: one JSON event per `data:` line (`started`, then `activity`, `text` and `artifact` events, then `done`, or `error`). Without it the final `done` event comes back as JSON, with the artifacts. The request must come from a person in a browser on the site; a script is refused. A prompt that fails on our side before it has done any work is not counted.",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "The public API major version. Omit it for version 1. An unsupported value returns 400. See https://stellarfirm.ai/docs/api/policy.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          }
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrialPromptRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The assistant's work, as a stream of events or as the final JSON answer.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "example": "data: {\"type\":\"started\",\"assistant\":\"coder\",\"promptsLeft\":2}\n\ndata: {\"type\":\"done\",\"answer\":\"Done.\",\"promptsLeft\":2}\n\n"
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/TrialPromptDone"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "The prompt is not valid, the request names no network address, or the API-Version header is unsupported. The `error.code` is `invalid_request`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "The request did not pass the check that a person sent it. The `error.code` is `try_refused`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "The free trial is switched off. The `error.code` is `not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "413": {
            "description": "The request is far larger than a prompt. The `error.code` is `too_large`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "The visitor used every free prompt (`try_used_up`, with `promptsLeft`), a prompt is already running, or too many run at once (`try_busy`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "502": {
            "description": "The prompt could not be answered. The `error.code` is `try_failed`, and `error.promptsLeft` says how many prompts are left.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "This month's free trial is used up (`try_ended`, with `reopensOn`), the check that a person sent it could not run (`try_refused`), or the trial could not start (`unavailable`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "The public API major version used for this response.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Link to the versioning and deprecation policy (rel=deprecation).",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "The signed-in account's session token, sent as `Authorization: Bearer <token>`. The StellarFirm desktop app and the phone app use it. See https://stellarfirm.ai/docs/api/authentication."
      },
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "__session",
        "description": "The session cookie the browser holds after you sign in at /sign-in. Sent automatically by a browser."
      }
    },
    "responses": {
      "MethodNotAllowed": {
        "description": "The route does not accept that HTTP method. The `Allow` header lists the ones it does. The `error.code` is `method_not_allowed`.",
        "headers": {
          "Allow": {
            "description": "The methods this route accepts.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "schemas": {
      "ApiError": {
        "type": "object",
        "description": "Every failure from a public route has this shape. Branch on `error.code`; it does not change between releases.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ApiErrorDetail"
          }
        },
        "examples": [
          {
            "error": {
              "code": "not_found",
              "message": "There is no API route at /api/nothing-here.",
              "hint": "Read the route list at /openapi.json, or start at /docs/api.",
              "docs": "https://stellarfirm.ai/docs/api/errors"
            }
          }
        ]
      },
      "ApiErrorDetail": {
        "type": "object",
        "required": [
          "code",
          "message",
          "hint",
          "docs"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "A stable machine-readable code.",
            "enum": [
              "not_found",
              "method_not_allowed",
              "signed_out",
              "forbidden",
              "ceo_only",
              "forbidden_origin",
              "rate_limited",
              "invalid_request",
              "invalid_token",
              "not_configured",
              "balance_unavailable",
              "credits_not_configured",
              "billing_not_configured",
              "paid_only",
              "crypto_checkout_off",
              "checkout_failed",
              "portal_failed",
              "bad_flow",
              "no_subscription",
              "unknown_plan",
              "not_an_upgrade",
              "unknown_pack",
              "limit_required",
              "limit_failed",
              "cancel_failed",
              "invalid_signature",
              "fulfilment_failed",
              "unavailable",
              "upstream_failed",
              "too_large",
              "try_used_up",
              "try_ended",
              "try_busy",
              "try_refused",
              "try_failed",
              "unknown_format",
              "plan_required",
              "busy",
              "thread_limit",
              "thread_full",
              "storage_full",
              "idempotency_conflict",
              "unreadable",
              "compaction_failed",
              "out_of_credits",
              "budget_reached",
              "guardrail_cbrn",
              "no_model",
              "internal_error"
            ],
            "examples": [
              "signed_out"
            ]
          },
          "message": {
            "type": "string",
            "description": "What went wrong, in one plain sentence."
          },
          "hint": {
            "type": "string",
            "description": "What to do next."
          },
          "docs": {
            "type": "string",
            "format": "uri",
            "description": "Where the error codes are explained.",
            "examples": [
              "https://stellarfirm.ai/docs/api/errors"
            ]
          },
          "reopensOn": {
            "type": "string",
            "format": "date",
            "description": "Only on `try_ended`: the day the free trial opens again (UTC)."
          },
          "promptsLeft": {
            "type": "integer",
            "minimum": 0,
            "description": "Only on `try_used_up`: the free prompts left, which is 0."
          }
        }
      },
      "Health": {
        "type": "object",
        "required": [
          "ok",
          "service",
          "surface",
          "agent"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "service": {
            "type": "string",
            "description": "A fixed identifier for the web service."
          },
          "surface": {
            "type": "string",
            "description": "Which part of the product answered."
          },
          "agent": {
            "type": "string",
            "description": "Whether assistants run in this service."
          }
        }
      },
      "SiteBanner": {
        "type": "object",
        "required": [
          "kind",
          "message"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "promo",
              "warning"
            ],
            "description": "A `promo` shows on the public site only. A `warning` shows everywhere."
          },
          "message": {
            "type": "string",
            "description": "The notice text."
          }
        }
      },
      "SiteBannerResponse": {
        "type": "object",
        "required": [
          "banner"
        ],
        "properties": {
          "banner": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SiteBanner"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "EntitlementAllowed": {
        "type": "object",
        "required": [
          "ok",
          "status",
          "recheckAfterSeconds"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "status": {
            "type": "string",
            "enum": [
              "licensed",
              "trial",
              "hobby"
            ]
          },
          "trialEndsAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the trial ends. Present on a trial."
          },
          "assistantLimit": {
            "type": "integer",
            "minimum": 0,
            "description": "How many named assistants the account may hire."
          },
          "teamLimit": {
            "type": "integer",
            "minimum": 1,
            "description": "How many teams of assistants the account may have, the first team included. Absent means the plan puts no cap on teams."
          },
          "recheckAfterSeconds": {
            "type": "integer",
            "minimum": 1,
            "description": "Ask again within this many seconds."
          }
        }
      },
      "EntitlementDenied": {
        "type": "object",
        "description": "The account may not run. It carries the `ApiError` fields too, so a client can branch on `error.code`.",
        "required": [
          "ok",
          "status",
          "message",
          "error"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "status": {
            "type": "string",
            "enum": [
              "signed-out",
              "invalid",
              "unconfigured",
              "unavailable"
            ]
          },
          "message": {
            "type": "string"
          },
          "error": {
            "$ref": "#/components/schemas/ApiErrorDetail"
          }
        }
      },
      "CreditsBalance": {
        "type": "object",
        "required": [
          "credits"
        ],
        "properties": {
          "credits": {
            "type": "number",
            "minimum": 0,
            "description": "The balance, as a count of credits."
          }
        }
      },
      "TrialStatus": {
        "type": "object",
        "required": [
          "open",
          "promptsLeft",
          "promptsPerVisitor"
        ],
        "properties": {
          "open": {
            "type": "boolean",
            "description": "False once this month's allowance for the free trial is used up."
          },
          "promptsLeft": {
            "type": "integer",
            "minimum": 0,
            "description": "Free prompts this visitor has left."
          },
          "promptsPerVisitor": {
            "type": "integer",
            "minimum": 1,
            "description": "Free prompts each visitor gets."
          },
          "reopensOn": {
            "type": "string",
            "format": "date",
            "description": "The day the trial opens again (UTC). Present only while it is closed."
          }
        }
      },
      "TrialPromptRequest": {
        "type": "object",
        "required": [
          "assistant",
          "content"
        ],
        "properties": {
          "assistant": {
            "type": "string",
            "enum": [
              "coder",
              "marketing",
              "product-owner"
            ],
            "description": "Which assistant gets the prompt."
          },
          "content": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000,
            "description": "The prompt, at most 2000 characters once trimmed."
          }
        }
      },
      "TrialArtifact": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "title"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "html",
              "svg",
              "markdown",
              "csv",
              "json",
              "other"
            ],
            "description": "A kind the page draws, or `other` for what is only listed."
          },
          "title": {
            "type": "string"
          },
          "content": {
            "type": "string",
            "description": "The file's text, for a kind the page draws and when it is small enough."
          }
        }
      },
      "TrialPromptDone": {
        "type": "object",
        "required": [
          "type",
          "answer",
          "promptsLeft"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "done"
          },
          "answer": {
            "type": "string",
            "description": "The whole answer, Markdown."
          },
          "promptsLeft": {
            "type": "integer",
            "minimum": 0,
            "description": "Free prompts this visitor has left."
          },
          "held": {
            "type": "boolean",
            "description": "True when the answer stopped at a step that needs an Approve, which a free prompt never gets."
          },
          "artifacts": {
            "type": "array",
            "description": "What the assistant published. Present when the answer is read as JSON.",
            "items": {
              "$ref": "#/components/schemas/TrialArtifact"
            }
          }
        }
      }
    }
  }
}
