stipple-sh Keys & usage API

openapi: 3.2.0
info:
  title: Stipple Sh Keys & usage API
  version: 0.6.0
  contact:
    name: Stipple
    url: https://www.stipple.sh/contact
  license:
    name: Security & terms
    url: https://www.stipple.sh/security
  description: 'Operations tagged Keys & usage across 2 of this provider''s published API definitions: www.stipple.sh-openapi.json, stipple-sh-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.stipple.sh
  description: Production
tags:
- name: Keys & usage
  description: Self-serve API keys and usage metering.
paths:
  /v1/keys:
    get:
      tags:
      - Keys & usage
      summary: List Api Keys
      description: List this account's key metadata. Plaintext keys and hashes never leave storage.
      operationId: list_api_keys_v1_keys_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Api Keys V1 Keys Get
    post:
      tags:
      - Keys & usage
      summary: Create Api Key
      description: 'Self-serve API key issuance. The key is returned ONCE and never stored in plaintext —

        only its hash. A keyed caller gets a weekly allowance of its own instead of sharing the

        per-IP one, and can read its metered usage via ``GET /v1/usage``.


        Sign in first and the key is linked to your account (``user_id``), so keys, credits and

        history are one identity rather than three that share an unproven email. Whether an

        anonymous caller may mint is ``config.key_mint_needs_session``: never under the TRIAL

        model (the balance a key spends is the account''s), and never while

        OPENWARRANT_REQUIRE_KEY_LOGIN is on and sign-in is configured (owner decision

        2026-08-23; this route stopped reading the flag on 2026-08-28 and reads it again from

        2026-09-30). Keys minted anonymously before that stay valid and can be linked to an

        account by proving possession (``POST /v1/account/keys/link``).'
      operationId: create_api_key_v1_keys_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKeyBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Create Api Key V1 Keys Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/mcp/connector:
    post:
      tags:
      - Keys & usage
      summary: Create Mcp Connector
      description: 'Mint this account''s MCP connector URL — ``/mcp/c/`` — for chat-assistant

        connector dialogs that take a server URL and no header. The token is an API key

        scoped to MCP (see ``keys.build_key_record``); it is shown ONCE, counts toward the

        per-account key cap, and is revoked like any key (``DELETE /v1/keys/{key_id}``).'
      operationId: create_mcp_connector
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Create Mcp Connector
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/keys/{key_id}:
    delete:
      tags:
      - Keys & usage
      summary: Revoke Api Key
      description: Disable one owned key. Revocation is immediate and cannot expose the key material.
      operationId: revoke_api_key_v1_keys__key_id__delete
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Revoke Api Key V1 Keys  Key Id  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/account/keys/link:
    post:
      tags:
      - Keys & usage
      summary: Link Api Key
      description: Prove possession of an anonymous key and attach it to the signed-in account.
      operationId: link_api_key_v1_account_keys_link_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkKeyBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Link Api Key V1 Account Keys Link Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/usage:
    get:
      tags:
      - Keys & usage
      summary: Get Usage
      description: 'Metered usage and credit balance for the caller — an API key (Authorization: Bearer)

        or a signed-in session (the account page reads this). Reads the same daily counters the

        rate limiter writes, so reported usage always matches enforcement.'
      operationId: get_usage_v1_usage_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get Usage V1 Usage Get
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/billing/history:
    get:
      tags:
      - Keys & usage
      summary: Billing History
      description: 'Safe account credit ledger: no Stripe ids, key hashes, or customer details.'
      operationId: billing_history_v1_billing_history_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Billing History V1 Billing History Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/pricing:
    get:
      tags:
      - Keys & usage
      summary: Get Pricing
      description: 'Public pricing document: the weekly free-checks cap on every free tool, and

        the flat price per tender for preparing a bid. The frontend pricing page and the docs read THIS —

        api/credits.py is the single source of truth.'
      operationId: get_pricing_v1_pricing_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get Pricing V1 Pricing Get
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/billing/checkout:
    post:
      tags:
      - Keys & usage
      summary: Billing Checkout
      description: 'Start a credit-pack purchase: returns the hosted Stripe Checkout URL.


        Requires a durable identity to attach the credits to — either a signed-in session

        (the website''s one-click path) or an API key as ``Authorization: Bearer``. Both prove

        ownership of the balance being topped up; an anonymous caller has nowhere to put

        credits, so it is asked to sign in first.'
      operationId: billing_checkout_v1_billing_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Billing Checkout V1 Billing Checkout Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
components:
  schemas:
    CreateKeyBody:
      properties:
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
      type: object
      title: CreateKeyBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CheckoutBody:
      properties:
        pack:
          type: string
          title: Pack
      type: object
      required:
      - pack
      title: CheckoutBody
    LinkKeyBody:
      properties:
        api_key:
          type: string
          title: Api Key
      type: object
      required:
      - api_key
      title: LinkKeyBody
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
x-refined-from:
- www.stipple.sh-openapi.json
- stipple-sh-openapi.json