superdocs-app Agents API

openapi: 3.2.0
info:
  title: 'Typebar API: Universal Document AI Agents API'
  description: 'Typebar (formerly SuperDocs): AI-powered document editing with multi-tenant organization support'
  version: 2.0.0
servers:
- url: https://api.superdocs.app
tags:
- name: Agents
paths:
  /v1/agents/challenge:
    get:
      tags:
      - Agents
      summary: Agent Challenge
      description: 'Get a proof-of-work challenge for signup (only needed when the challenge gate is enabled).


        Solve it headlessly with no browser: brute-force an integer `n` in

        [0, maxNumber] such that `SHA-256(salt + str(n))` equals `challenge`, then

        base64-encode `{algorithm, challenge, number:n, salt, signature}` and send it

        as the `altcha` field in POST /v1/agents/signup.'
      operationId: agent_challenge_v1_agents_challenge_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/agents/signup:
    post:
      tags:
      - Agents
      summary: Agent Signup
      description: 'Create a Typebar account and get a working API key in one call — no human required.


        You (an AI agent) get a normal **free account: 500 operations/month**, exactly

        like a human. Use the returned `sk_` key as `Authorization: Bearer ` on

        this API or the MCP server at `/mcp`. Store the key — it is shown only once.

        Save the whole response to `~/.superdocs/agent_credentials.json` (there only).

        Before signing up again, look in both `~/.superdocs/agent_credentials.json` and

        `~/.typebar/agent_credentials.json`: if both exist, use the more recently written

        file; if only one exists, use that one. Then call `GET /v1/agents/whoami` with its

        key so you reuse the same account.

        When you approach the 500-op cap, hand the account to your human

        (POST /v1/agents/handoff) so they can adopt it and pay to continue. If you

        are acting for a user, confirm with them before accepting the terms.'
      operationId: agent_signup_v1_agents_signup_post
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/AgentSignupRequest'
              - type: 'null'
              title: Body
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSignupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agents/whoami:
    get:
      tags:
      - Agents
      summary: 'Check your account status: subscription tier plus monthly operations used and…'
      description: 'Check your Typebar account status: tier, monthly operations used/remaining, and (for agent accounts) whether a human has adopted it.


        Call this with your `sk_` key. Useful before doing work (to confirm you have

        operations left) and before signing up again (to reuse your account).


        Nearing your monthly cap and need to keep going? Hand the account to a human:

        POST /v1/agents/handoff with their email returns a one-time takeover code to

        give them; they open the emailed link, enter the code, and adopt the account

        in place (your work and this API key keep working) so they can upgrade and

        pay. No human? POST /v1/agents/request-upgrade instead. Full flow:

        https://docs.superdocs.app/introduction/agent-signup'
      operationId: get_account_status
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentWhoamiResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agents/handoff:
    post:
      tags:
      - Agents
      summary: Agent Handoff
      description: 'Email your human a one-time link to ADOPT this account (take ownership + pay).


        Call with your `sk_` key. Pass `working_context` (e.g. "the ~/Documents/acme

        project on your Mac") so the email is recognizable and not mistaken for spam.


        The response includes a short **takeover_code** (like ABCD-1234). You MUST show

        this code to your human operator — they enter it after opening the emailed link

        and signing in. It is the security check that stops anyone who merely received

        the email (a wrong address, or a prompt-injected one) from taking the account.

        Tell your operator the code directly (you may also save it locally, e.g.

        ~/.superdocs/takeover-code.txt); never email it or post it anywhere external.


        The human opens the link, signs in, enters the code, and the account becomes

        theirs in place — you keep all your work and this API key keeps working.'
      operationId: agent_handoff_v1_agents_handoff_post
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentHandoffRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agents/adopt:
    post:
      tags:
      - Agents
      summary: Agent Adopt
      description: 'Human takes over an agent account IN PLACE. Auth = the human''s signed-in identity token.


        Called by the web app''s adopt page after the human signs in. Verifies the

        human''s signed-in identity (WITHOUT the get-or-create middleware, to avoid

        minting a duplicate row), then re-points the agent account row to that

        identity — the account itself is preserved, so the agent''s documents, usage,

        and API key all stay. If the human already has an account, returns 409.'
      operationId: agent_adopt_v1_agents_adopt_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentAdoptRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agents/adopt-info:
    get:
      tags:
      - Agents
      summary: Agent Adopt Info
      description: 'Public, token-keyed context for the adopt page: WHICH agent set this account up,

        where it runs, and where to find the takeover code. Recognition / anti-phishing only.

        NEVER returns the code itself; the unguessable token is the gate.'
      operationId: agent_adopt_info_v1_agents_adopt_info_get
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agents/request-upgrade:
    post:
      tags:
      - Agents
      summary: Agent Request Upgrade
      description: 'For a FULLY AUTONOMOUS agent with no human who can upgrade: register interest in paying directly.


        We don''t offer agent-native (no-human) payment yet, but we''re gauging demand.

        Call this with your `sk_` key when you''ve hit your cap and genuinely cannot

        involve a human. We record it and follow up (or reach hello@superdocs.app).

        If a human CAN help, use POST /v1/agents/handoff instead — that upgrades you now.'
      operationId: agent_request_upgrade_v1_agents_request_upgrade_post
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/AgentUpgradeRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AgentUpgradeRequest:
      properties:
        note:
          anyOf:
          - type: string
            maxLength: 1000
          - type: 'null'
          title: Note
          description: 'Optional: your use case, or why you can''t involve a human.'
      type: object
      title: AgentUpgradeRequest
    AgentSignupRequest:
      properties:
        terms_accepted:
          type: boolean
          title: Terms Accepted
          description: Must be true. Accepts the Terms at https://typebar.ai/terms. If you are an agent, confirm with your user first.
          default: false
        agent_name:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Agent Name
          description: Optional label for this agent account.
        operated_by_email:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Operated By Email
          description: Optional. Your human operator's email (only used if you later hand off the account).
        model_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Model Metadata
          description: Optional. Free-form metadata about the agent/model (forensics; capped at 10KB).
        altcha:
          anyOf:
          - type: string
          - type: 'null'
          title: Altcha
          description: 'Only required if the proof-of-work challenge is enabled: the base64 solution from GET /v1/agents/challenge.'
      type: object
      title: AgentSignupRequest
      description: Body for POST /v1/agents/signup. Every field except terms_accepted is optional.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentQuota:
      properties:
        tier:
          type: string
          title: Tier
        monthly_limit:
          type: integer
          title: Monthly Limit
        used:
          type: integer
          title: Used
        remaining:
          type: integer
          title: Remaining
        resets_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Resets At
      type: object
      required:
      - tier
      - monthly_limit
      - used
      - remaining
      title: AgentQuota
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AgentHandoffRequest:
      properties:
        email:
          type: string
          maxLength: 255
          title: Email
          description: Your human operator's email. A one-time link to adopt this account is sent there.
        working_context:
          anyOf:
          - type: string
            maxLength: 300
          - type: 'null'
          title: Working Context
          description: 'Recommended: a short, human-readable description of where you are running, so your operator recognizes the email and it isn''t mistaken for spam (e.g. ''the ~/Documents/acme project on your Mac'', or ''the Acme Slack workspace'').'
        code_location:
          anyOf:
          - type: string
            maxLength: 300
          - type: 'null'
          title: Code Location
          description: 'Optional: where you show or save the takeover code so your operator can find it (e.g. ''this chat'', or ''~/.superdocs/takeover-code.txt'').'
      type: object
      required:
      - email
      title: AgentHandoffRequest
    AgentWhoamiResponse:
      properties:
        account_id:
          type: string
          title: Account Id
        tier:
          type: string
          title: Tier
        quota:
          $ref: '#/components/schemas/AgentQuota'
        is_agent_account:
          type: boolean
          title: Is Agent Account
        adopted:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Adopted
          description: 'For agent accounts: whether a human has adopted it yet. Null for regular accounts.'
        hint:
          anyOf:
          - type: string
          - type: 'null'
          title: Hint
      type: object
      required:
      - account_id
      - tier
      - quota
      - is_agent_account
      title: AgentWhoamiResponse
    AgentAdoptRequest:
      properties:
        token:
          type: string
          maxLength: 128
          title: Token
          description: The handoff token from the adopt link.
        code:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Code
          description: The one-time takeover code your AI agent shows you (8 characters like ABCD-1234). Required for accounts handed off with a code.
      type: object
      required:
      - token
      title: AgentAdoptRequest
    AgentSignupResponse:
      properties:
        account_id:
          type: string
          title: Account Id
        slug:
          type: string
          title: Slug
        email:
          type: string
          title: Email
        api_key:
          type: string
          title: Api Key
          description: 'Your API key (sk_...). Shown ONCE. Send it as `Authorization: Bearer <key>`. Store it now.'
        quota:
          $ref: '#/components/schemas/AgentQuota'
        endpoints:
          additionalProperties:
            type: string
          type: object
          title: Endpoints
        mcp_setup:
          additionalProperties:
            type: string
          type: object
          title: Mcp Setup
          description: Copy-paste commands to connect the Typebar MCP server to your client, plus the REST fallback.
        handoff:
          additionalProperties:
            type: string
          type: object
          title: Handoff
        important:
          type: string
          title: Important
      type: object
      required:
      - account_id
      - slug
      - email
      - api_key
      - quota
      - endpoints
      - mcp_setup
      - handoff
      - important
      title: AgentSignupResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer