Fastn API

openapi: 3.1.0
info:
  title: Fastn API
  version: '2026-10-20'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-20: 14 operation(s) read from 12 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; Fastn has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 2
    documentation: 12
    pages-with-code: 4
    pages-read: 12
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-20'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.fastn.ai/reference/api
  - https://docs.fastn.ai/reference/api.md
  - https://docs.fastn.ai/reference/faqs.md
  - https://docs.fastn.ai/reference/ai-agents
  - https://docs.fastn.ai/reference/errors.md
  - https://docs.fastn.ai/reference/glossary.md
  - https://docs.fastn.ai/reference/ai-agents.md
  - https://docs.fastn.ai/reference/workflow-runtime
  - https://docs.fastn.ai/reference/workflow-runtime.md
  - https://docs.fastn.ai/manage/api-keys.md
  - https://docs.fastn.ai/build/unified-apis.md
  - https://docs.fastn.ai/embed/embedding/sdk.md
servers:
- url: https://api.fastn.dev
paths:
  /:
    post:
      operationId: post
      tags:
      - Api
      summary: POST /
      x-source: https://docs.fastn.ai/reference/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl. Base URL Production base URL: https://api.fastn.dev . Your workflow''s API tab shows the URL for your workspace. Examples
          below use YOUR_FASTN_HOST . Authentication Every request carries an API key as a bearer token. Keys are created under Settings → API
          keys and come in two modes. Header Live key Test key Authorization Bearer fsk_live_… Bearer fsk_test_… X-fastn-Test-Mode Not needed
          Must be '
  /api/v1/embed/iframe:
    get:
      operationId: get_api_v1_embed_iframe
      tags:
      - Api
      summary: Get embed iframe URL
      x-source: https://docs.fastn.ai/reference/ai-agents
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
        description: Embed token (e.g., emb_… )
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/embed/token:
    post:
      operationId: post_api_v1_embed_token
      tags:
      - Api
      summary: Mint an embed token
      description: Generates a token that scopes an embedded widget to a specific customer.
      x-source: https://docs.fastn.ai/reference/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1EmbedTokenRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1EmbedTokenResponse'
      x-evidence:
        kind: documentation
  /api/v1/embed/token/refresh:
    post:
      operationId: post_api_v1_embed_token_refresh
      tags:
      - Api
      summary: Refresh an embed token
      description: Refreshes an existing embed token; refreshes are limited to a maximum of seven days per session.
      x-source: https://docs.fastn.ai/reference/api
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1EmbedTokenRefreshResponse'
      x-evidence:
        kind: documentation
  /api/v1/unified/{category}/{entity}:
    get:
      operationId: get_api_v1_unified_category_entity
      tags:
      - Api
      summary: List unified entities
      x-source: https://docs.fastn.ai/reference/ai-agents
      parameters:
      - name: category
        in: path
        required: true
        schema:
          type: string
      - name: entity
        in: path
        required: true
        schema:
          type: string
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
        description: Number of records per page
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_unified_category_entity
      tags:
      - Api
      summary: Create a unified entity record
      x-source: https://docs.fastn.ai/reference/ai-agents
      parameters:
      - name: category
        in: path
        required: true
        schema:
          type: string
      - name: entity
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1UnifiedCategoryEntityRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/unified/{category}/{entity}/{recordid}:
    get:
      operationId: get_api_v1_unified_category_entity_recordid
      tags:
      - Api
      summary: Retrieve a single unified record
      x-source: https://docs.fastn.ai/reference/ai-agents
      parameters:
      - name: category
        in: path
        required: true
        schema:
          type: string
      - name: entity
        in: path
        required: true
        schema:
          type: string
      - name: recordid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/workflows/{workflowid}/execute:
    post:
      operationId: post_api_v1_workflows_workflowid_execute
      tags:
      - Api
      summary: Execute a workflow
      description: Runs the specified workflow. Instant tier returns the workflow's output inline; Standard and Long tiers return a 202 Accepted
        with an execution id.
      x-source: https://docs.fastn.ai/reference/api
      parameters:
      - name: workflowid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1WorkflowsWorkflowidExecuteRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1WorkflowsWorkflowidExecuteResponse'
      x-evidence:
        kind: documentation
  /build/unified-apis.md:
    get:
      operationId: get_build_unified_apis_md
      tags:
      - Build
      summary: Unified APIs
      description: Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters to retrieve a direct answer and
        relevant excerpts from the documentation.
      x-source: https://docs.fastn.ai/build/unified-apis.md
      parameters:
      - name: ask
        in: query
        required: false
        schema:
          type: string
        description: The immediate question, specific and self‑contained, written in natural language.
      - name: goal
        in: query
        required: false
        schema:
          type: string
        description: The user’s ultimate goal, describing the outcome they want to achieve.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /embed/embedding/sdk.md:
    get:
      operationId: get_embed_embedding_sdk_md
      tags:
      - Embed
      summary: Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters
      x-source: https://docs.fastn.ai/embed/embedding/sdk.md
      parameters:
      - name: ask
        in: query
        required: false
        schema:
          type: string
        description: The immediate question, specific and self‑contained, written in natural language.
      - name: goal
        in: query
        required: false
        schema:
          type: string
        description: The user’s ultimate goal, describing the outcome they want to achieve.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /fastn-workspace:
    get:
      operationId: get_fastn_workspace
      tags:
      - Fastn Workspace
      summary: GET /fastn-workspace
      x-source: https://docs.fastn.ai/reference/ai-agents
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: curl with your host, workflow id and contract fields Workflow → Connectors tab Which connectors and action versions are actually
          bound, and per-customer vs workspace scope Connector detail page The action list, and the Select all control that scopes them When this
          page and a generated tab disagree, the tab is right. Machine-readable formats This documentation is published from GitBook, which serve
  /reference/errors.md:
    get:
      operationId: get_reference_errors_md
      tags:
      - Reference
      summary: Errors and failure states
      description: Performs an HTTP GET request to retrieve an answer from the documentation based on the provided `ask` and `goal` query parameters.
      x-source: https://docs.fastn.ai/reference/errors.md
      parameters:
      - name: ask
        in: query
        required: false
        schema:
          type: string
        description: The immediate question to ask the documentation, written in natural language.
      - name: goal
        in: query
        required: false
        schema:
          type: string
        description: The broader goal behind the question, helping to tailor the answer.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /reference/faqs.md:
    get:
      operationId: get_reference_faqs_md
      tags:
      - Reference
      summary: FAQs
      description: Performs an HTTP GET request to retrieve the FAQ page, optionally providing `ask` and `goal` query parameters to get a direct
        answer from the documentation.
      x-source: https://docs.fastn.ai/reference/faqs.md
      parameters:
      - name: ask
        in: query
        required: false
        schema:
          type: string
        description: The immediate question to ask, specific and self‑contained, written in natural language.
      - name: goal
        in: query
        required: false
        schema:
          type: string
        description: The broader user goal, describing the outcome the user wants to achieve.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /reference/glossary.md:
    get:
      operationId: get_reference_glossary_md
      tags:
      - Reference
      summary: Glossary
      description: Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters to retrieve a direct answer from
        the documentation.
      x-source: https://docs.fastn.ai/reference/glossary.md
      parameters:
      - name: ask
        in: query
        required: false
        schema:
          type: string
        description: 'The immediate question: it should be specific, self-contained, and written in natural language.'
      - name: goal
        in: query
        required: false
        schema:
          type: string
        description: The user’s ultimate goal, describing the outcome they want to achieve.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostRequest:
      type: object
      properties:
        input:
          type: object
          properties:
            saleId:
              type: string
            isRetry:
              type: boolean
            syncMode:
              type: string
    PostResponse:
      type: object
      properties:
        endOrgId:
          type: string
    PostApiV1EmbedTokenRequest:
      type: object
      properties:
        endOrgId:
          type: string
          description: Customer organization ID the token is scoped to
        role:
          type: string
          description: Role for the token, always "end_user"
        expiresIn:
          type: integer
          description: Token lifetime in seconds (default 28800 seconds = 8 hours)
      required:
      - endOrgId
      - role
      - expiresIn
    PostApiV1EmbedTokenResponse:
      type: object
      properties:
        token:
          type: string
          description: The minted embed token (e.g., emb_…)
        endOrgId:
          type: string
          description: Echo of the organization ID the token is scoped to
        role:
          type: string
          description: Echo of the role (always end_user)
        expiresIn:
          type: integer
          description: Echo of the token expiration time in seconds
    PostApiV1EmbedTokenRefreshResponse:
      type: object
      properties:
        token:
          type: string
          description: A new embed token
        expiresIn:
          type: integer
          description: New token lifetime in seconds
    PostApiV1UnifiedCategoryEntityRequest:
      type: object
      properties:
        input:
          type: object
          description: Data for the new record
    PostApiV1WorkflowsWorkflowidExecuteRequest:
      type: object
      properties:
        input:
          type: object
          description: Workflow input object as defined by the workflow's input contract
      required:
      - input
    PostApiV1WorkflowsWorkflowidExecuteResponse:
      type: object
      properties:
        input:
          type: object
          description: Echo of the input object (for instant tier responses)
        executionId:
          type: string
          description: Execution identifier returned for Standard and Long tier runs (e.g., exec_…)
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Build
- name: Embed
- name: Fastn Workspace
- name: Reference