Awzor Media LLC Keys API

openapi: 3.2.0
info:
  title: Hook Detector Keys API
  description: 'Find short-form hooks that already work.


    Sign up with a beta access code (ask at https://hookdetector.com/access): one POST to

    `/v1/accounts` with `access_code` gives an API key and free credits. The same operations are available as MCP tools at `/mcp`.


    Full guide, always current, at `/llms.txt`.'
  contact:
    name: Hook Detector
    url: https://hookdetector.com/
    email: contact@hookdetector.com
  version: 3.0.0
tags:
- name: Keys
paths:
  /v1/keys:
    get:
      tags:
      - Keys
      summary: Your API keys and what each may do. Never the keys themselves
      description: 'Every key not revoked: in keys, key_id, name, prefix, created_at, last_used_at

        (updated at most every 5 minutes) and current (true for the key making this call); in

        access, per key_id, its scopes, credit_limit, credits_used (what runs started with it

        spent), expires_at and expired. scopes is the calling key''s. The signup key is key_id

        "original". A key itself is never shown again. Needs admin. MCP: list_keys.'
      operationId: list_keys_v1_keys_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Bearer hd_... from POST /v1/accounts or POST /v1/keys
          title: Authorization
        description: Bearer hd_... from POST /v1/accounts or POST /v1/keys
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyList'
        '401':
          description: missing, invalid, revoked or expired API key (code key_expired)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '403':
          description: the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '413':
          description: request body over the size cap
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '422':
          description: invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '500':
          description: our fault; names the request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
    post:
      tags:
      - Keys
      summary: Create another API key. The key is in this response only
      description: 'A new key on the same account, for example one per agent or machine, so one can be

        revoked without touching the others. Give it only what it needs: scopes (read, write,

        research, admin; all four when left out), credit_limit (the most its runs may spend

        over its life, 1 to 100000) and expires_in_days (1 to 365). The full key is in this

        response and nowhere else, ever. Needs admin. 409 key_limit_reached at 10 active

        keys; creation is limited per account per hour (429). MCP: create_key.'
      operationId: create_key_v1_keys_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Bearer hd_... from POST /v1/accounts or POST /v1/keys
          title: Authorization
        description: Bearer hd_... from POST /v1/accounts or POST /v1/keys
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/KeyIn'
              - type: 'null'
              title: Body
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyCreatedOut'
        '401':
          description: missing, invalid, revoked or expired API key (code key_expired)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '403':
          description: the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '409':
          description: conflict with the account's state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '413':
          description: request body over the size cap
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '422':
          description: invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '429':
          description: rate limited; see Retry-After
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '500':
          description: our fault; names the request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
  /v1/keys/{key_id}:
    delete:
      tags:
      - Keys
      summary: Revoke a key ("original", a key_id, or "others" for all but yours)
      description: 'Revoke one key at once. You may revoke the key you are calling with, whatever its

        scopes (the response says so in current); revoking another needs admin. Never the last

        usable key (409 last_active_key: create another first). An unknown or already revoked

        key is 404 key_not_found. key_id "others" revokes every key of the account except the

        one calling, for a key that leaked, and answers revoked_count and kept. MCP:

        revoke_key.'
      operationId: revoke_key_v1_keys__key_id__delete
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Bearer hd_... from POST /v1/accounts or POST /v1/keys
          title: Authorization
        description: Bearer hd_... from POST /v1/accounts or POST /v1/keys
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyRevokedOut'
        '401':
          description: missing, invalid, revoked or expired API key (code key_expired)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '403':
          description: the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '404':
          description: not found on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '409':
          description: conflict with the account's state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '413':
          description: request body over the size cap
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '422':
          description: invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '500':
          description: our fault; names the request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
components:
  schemas:
    KeyAccess:
      properties:
        scopes:
          items:
            type: string
            enum:
            - read
            - write
            - research
            - admin
          type: array
          title: Scopes
        credit_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credit Limit
          description: 'null: no cap'
        credits_used:
          type: integer
          title: Credits Used
          description: charged by settled runs started with this key, plus what its runs in flight hold
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
          description: 'null: never expires'
        expired:
          type: boolean
          title: Expired
      additionalProperties: true
      type: object
      required:
      - scopes
      - credit_limit
      - credits_used
      - expires_at
      - expired
      title: KeyAccess
    ErrorOut:
      properties:
        detail:
          type: string
          title: Detail
          description: one sentence a person can read
        code:
          type: string
          title: Code
          description: stable machine code; see the Errors section of /llms.txt
        errors:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Errors
          description: 'on a 422 only: the field level list'
      additionalProperties: true
      type: object
      required:
      - detail
      - code
      title: ErrorOut
      examples:
      - code: run_not_found
        detail: no such run for this account
    KeyRevokedOut:
      properties:
        key_id:
          type: string
          title: Key Id
        revoked:
          type: boolean
          title: Revoked
        revoked_at:
          type: string
          title: Revoked At
        current:
          type: boolean
          title: Current
        message:
          type: string
          title: Message
      additionalProperties: true
      type: object
      required:
      - key_id
      - revoked
      - revoked_at
      - current
      - message
      title: KeyRevokedOut
      examples:
      - current: false
        key_id: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
        message: Revoked. Calls with this key are refused from now on.
        revoked: true
        revoked_at: '2026-09-23T10:00:00.000000+00:00'
    KeyOut:
      properties:
        key_id:
          type: string
          title: Key Id
        name:
          type: string
          title: Name
        prefix:
          type: string
          title: Prefix
        created_at:
          type: string
          title: Created At
        last_used_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Used At
        current:
          type: boolean
          title: Current
      additionalProperties: true
      type: object
      required:
      - key_id
      - name
      - prefix
      - created_at
      - last_used_at
      - current
      title: KeyOut
    KeyList:
      properties:
        keys:
          items:
            $ref: '#/components/schemas/KeyOut'
          type: array
          title: Keys
        scopes:
          items:
            type: string
            enum:
            - read
            - write
            - research
            - admin
          type: array
          title: Scopes
          description: what the key making this call may do
        access:
          additionalProperties:
            $ref: '#/components/schemas/KeyAccess'
          type: object
          title: Access
          description: 'per key_id: its scopes, cap, spend and expiry'
      additionalProperties: true
      type: object
      required:
      - keys
      - scopes
      - access
      title: KeyList
      examples:
      - access:
          original:
            credits_used: 63
            expired: false
            scopes:
            - read
            - write
            - research
            - admin
        keys:
        - created_at: '2026-09-23T10:00:00.000000+00:00'
          current: true
          key_id: original
          last_used_at: '2026-09-23T10:00:00.000000+00:00'
          name: Original key
          prefix: hd_AbCdEfGh
        scopes:
        - read
        - write
        - research
        - admin
    KeyIn:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: up to 60 characters, to tell your keys apart; defaults to 'API key'
          examples:
          - ci runner
        scopes:
          items:
            type: string
            enum:
            - read
            - write
            - research
            - admin
          type: array
          minItems: 1
          uniqueItems: true
          title: Scopes
          description: 'what the key may do: read, write, research, admin. Left out: all four. Give an agent only what it needs, for example ["read", "write", "research"]'
          examples:
          - - read
            - write
            - research
        credit_limit:
          type: integer
          maximum: 100000.0
          minimum: 1.0
          title: Credit Limit
          description: 'the most credits runs started with this key may spend over its life, 1 to 100000; left out: no cap'
          examples:
          - 1000
        expires_in_days:
          type: integer
          maximum: 365.0
          minimum: 1.0
          title: Expires In Days
          description: 'the key stops working after this many days, 1 to 365; left out: never'
          examples:
          - 90
      type: object
      title: KeyIn
    KeyCreatedOut:
      properties:
        key_id:
          type: string
          title: Key Id
        name:
          type: string
          title: Name
        prefix:
          type: string
          title: Prefix
        api_key:
          type: string
          title: Api Key
          description: shown this once; store it now
        created_at:
          type: string
          title: Created At
      additionalProperties: true
      type: object
      required:
      - key_id
      - name
      - prefix
      - api_key
      - created_at
      title: KeyCreatedOut
      examples:
      - api_key: hd_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
        created_at: '2026-09-23T10:00:00.000000+00:00'
        key_id: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
        name: ci runner
        prefix: hd_ZyXwVuTs