Awzor Media LLC Accounts API

openapi: 3.2.0
info:
  title: Hook Detector Accounts 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: Accounts
paths:
  /v1/accounts:
    post:
      tags:
      - Accounts
      summary: Sign up with a beta access code. No auth, no form, no human step
      description: 'Create an account and get an API key with free credits. Needs a beta access code as

        `access_code` (403 access_code_required without one, 403 invalid_access_code for one

        that does not work; ask at hookdetector.com/access). The key in this response

        is the only copy that will ever exist: store it, then send it as

        `Authorization: Bearer hd_...` on every other call. Signups are limited per address per

        hour (an IPv6 caller per /64), and so are wrong codes; the X-RateLimit headers say

        where you stand. Free. MCP: create_account.'
      operationId: signup_v1_accounts_post
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/SignupIn'
              - type: 'null'
              title: Body
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupOut'
        '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'
        '403':
          description: 'no access code (access_code_required), or one that does not work (invalid_access_code): mistyped, used up, expired or revoked, one answer for all'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
  /v1/me:
    get:
      tags:
      - Accounts
      summary: Who am I, what is my balance, what may this key do
      description: 'The account behind the key: account_id, credits (the balance right now),

        key_prefix and key_id of the key making this call, label and created_at, and that

        key''s scopes, credit_limit and expires_at (null: no cap, never expires), and `user`:

        the person signed in with Google who uses the account (null for a key-only account).

        Needs read. Free. MCP: balance.'
      operationId: me_v1_me_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/MeOut'
        '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'
  /v1/account:
    delete:
      tags:
      - Accounts
      summary: Erase your account and everything in it
      description: 'Erase the account and every row it owns: all its API keys, runs, hooks, keep or

        reject decisions, conversations and messages. It cannot be undone. The body must be

        exactly `{"confirm": "delete my account"}` (422 confirmation_required otherwise), and

        it is refused with 409 run_in_flight while a run is still queued or running. Any

        unspent credits go with the account. Every key stops working at once. Needs admin.

        MCP: delete_account.'
      operationId: delete_account_v1_account_delete
      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/DeleteAccountIn'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountDeletedOut'
        '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'
        '500':
          description: our fault; names the request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
  /v1/usage:
    get:
      tags:
      - Accounts
      summary: Credits, spend, what in-flight runs hold, and the last 30 days
      description: 'credits (the balance now), spent_total (charged by finished runs), reserved_now

        (held by runs still in flight), runs_total, last_30_days (one entry per UTC day,

        oldest first) and recent (the 20 newest runs). credits + spent_total + reserved_now is

        everything the account was given. Needs read. Free. MCP: usage.'
      operationId: usage_v1_usage_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/UsageOut'
        '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'
components:
  schemas:
    SignupOut:
      properties:
        account_id:
          type: string
          title: Account Id
        api_key:
          type: string
          title: Api Key
          description: the only copy there will ever be; store it now
        credits:
          type: integer
          title: Credits
        created_at:
          type: string
          title: Created At
        message:
          type: string
          title: Message
        next:
          type: string
          title: Next
      additionalProperties: true
      type: object
      required:
      - account_id
      - api_key
      - credits
      - created_at
      - message
      - next
      title: SignupOut
      examples:
      - account_id: 8f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f
        api_key: hd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        created_at: '2026-09-23T10:00:00.000000+00:00'
        credits: 500
        message: This is the only copy of your key.
        next: POST /v1/research
    UsageRun:
      properties:
        run_id:
          type: string
          title: Run Id
        kind:
          type: string
          title: Kind
          description: 'short, long or packaging: which kind of research the run was'
          default: short
        topic:
          type: string
          title: Topic
        status:
          type: string
          title: Status
        reserved:
          type: integer
          title: Reserved
        charged:
          type: integer
          title: Charged
        created_at:
          type: string
          title: Created At
        finished_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Finished At
      additionalProperties: true
      type: object
      required:
      - run_id
      - topic
      - status
      - reserved
      - charged
      - created_at
      - finished_at
      title: UsageRun
    MeOut:
      properties:
        account_id:
          type: string
          title: Account Id
        credits:
          type: integer
          title: Credits
        key_prefix:
          type: string
          title: Key Prefix
        key_id:
          type: string
          title: Key Id
          description: 'the key making this call: "original" or a key id'
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        created_at:
          type: string
          title: Created At
        scopes:
          items:
            type: string
            enum:
            - read
            - write
            - research
            - admin
          type: array
          title: Scopes
          description: what the key making this call may do
        credit_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credit Limit
          description: the most this key's runs may spend over its life; null is no cap
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
          description: when this key stops working; null is never
        user:
          anyOf:
          - $ref: '#/components/schemas/SignedInUser'
          - type: 'null'
          description: the person signed in with Google who uses this account; null for an account made with a key alone
      additionalProperties: true
      type: object
      required:
      - account_id
      - credits
      - key_prefix
      - key_id
      - label
      - created_at
      - scopes
      - credit_limit
      - expires_at
      title: MeOut
      examples:
      - account_id: 8f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f
        created_at: '2026-09-23T10:00:00.000000+00:00'
        credits: 437
        key_id: original
        key_prefix: hd_AbCdEfGh
        scopes:
        - read
        - write
        - research
        - admin
    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
    UsageOut:
      properties:
        credits:
          type: integer
          title: Credits
        spent_total:
          type: integer
          title: Spent Total
        reserved_now:
          type: integer
          title: Reserved Now
        runs_total:
          type: integer
          title: Runs Total
        last_30_days:
          items:
            $ref: '#/components/schemas/UsageDay'
          type: array
          title: Last 30 Days
        recent:
          items:
            $ref: '#/components/schemas/UsageRun'
          type: array
          title: Recent
      additionalProperties: true
      type: object
      required:
      - credits
      - spent_total
      - reserved_now
      - runs_total
      - last_30_days
      - recent
      title: UsageOut
      examples:
      - credits: 437
        last_30_days:
        - charged: 63
          date: '2026-09-23'
          runs: 1
        recent: []
        reserved_now: 0
        runs_total: 1
        spent_total: 63
    DeleteAccountIn:
      properties:
        confirm:
          title: Confirm
          description: must be exactly "delete my account"
          examples:
          - delete my account
      type: object
      title: DeleteAccountIn
    UsageDay:
      properties:
        date:
          type: string
          title: Date
        runs:
          type: integer
          title: Runs
        charged:
          type: integer
          title: Charged
      additionalProperties: true
      type: object
      required:
      - date
      - runs
      - charged
      title: UsageDay
    AccountDeletedOut:
      properties:
        deleted:
          type: boolean
          title: Deleted
        account_id:
          type: string
          title: Account Id
        erased:
          additionalProperties:
            type: integer
          type: object
          title: Erased
          description: rows erased, per kind
        message:
          type: string
          title: Message
      additionalProperties: true
      type: object
      required:
      - deleted
      - account_id
      - erased
      - message
      title: AccountDeletedOut
      examples:
      - account_id: 8f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f
        deleted: true
        erased:
          api_keys: 1
          conversations: 2
          decisions: 9
          hooks: 24
          messages: 6
          runs: 3
        message: The account and everything in it are erased.
    SignupIn:
      properties:
        label:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Label
          description: your own note, to tell accounts apart
          examples:
          - my research agent
        access_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Access Code
          description: 'your beta access code, HD-XXXX-XXXX (case and dashes do not matter). Required: without it the answer is 403 access_code_required. Ask for one at hookdetector.com/access.'
          examples:
          - HD-7K3M-Q9TX
      type: object
      title: SignupIn
    SignedInUser:
      properties:
        email:
          type: string
          title: Email
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
        is_admin:
          type: boolean
          title: Is Admin
      additionalProperties: true
      type: object
      required:
      - email
      - name
      - avatar_url
      - is_admin
      title: SignedInUser