Awzor Media LLC Meta API

openapi: 3.2.0
info:
  title: Hook Detector Meta 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: Meta
paths:
  /health:
    get:
      tags:
      - Meta
      summary: 'Liveness: is the process up and can it reach the database'
      description: 'A cheap check for load balancers: always 200. status is ok, or degraded when the

        database does not answer. database is "up", "busy" (every pooled connection is in use

        right now: the service is loaded, not broken, and status stays ok) or "down". commit

        is the git commit this image was built from, "unknown" outside a deploy.

        runs_in_flight counts research runs queued or running across the service (null when

        the database did not answer): a restart waits for 0, because Railway''s in-place

        restart kills the process about 10 seconds after SIGTERM. It waits at most about 2

        seconds for a connection and never calls a provider.'
      operationId: health_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthOut'
  /health/deep:
    get:
      tags:
      - Meta
      summary: 'Readiness: database, migrations, provider keys, provider status'
      description: 'For monitoring and for the web: a timed database round trip, whether every

        migration this code needs is applied, whether each provider key is configured (never

        a value), and provider_status: whether the language model or the search provider is

        refusing right now, read from how recent runs ended (cached 30 seconds, never a paid

        probe), and for the search provider our own credits_left (read in the background at

        most every 10 minutes from its free balance endpoint, never on this request), low

        (under HD_SEARCH_CREDITS_LOW) and accepting_runs (false while it refuses us: new runs

        are then 503 search_unavailable). A refusing provider does not make this 503; it is a

        warning for new runs. fallback_providers says whether the optional anthropic model

        fallback is configured (never a value); it never makes this degraded.

        commit is the git commit the image was built from ("unknown" outside a deploy), and

        credits_today is how much of the global daily research ceiling is reserved (UTC day).

        database.state is "up", "busy" or "down". Busy means every pooled connection is in

        use: it answers 200 with status ok, the schema as last read, and no provider_status.'
      operationId: health_deep_health_deep_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthDeepOut'
        '503':
          description: 'degraded: database down, a migration missing or a provider key not configured'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthDeepOut'
components:
  schemas:
    HealthDeepOut:
      properties:
        status:
          type: string
          title: Status
        version:
          type: string
          title: Version
        database:
          additionalProperties: true
          type: object
          title: Database
        schema:
          additionalProperties: true
          type: object
          title: Schema
        providers:
          additionalProperties:
            type: boolean
          type: object
          title: Providers
        fallback_providers:
          anyOf:
          - additionalProperties:
              type: boolean
            type: object
          - type: 'null'
          title: Fallback Providers
          description: 'optional providers, configured or not (never a value): anthropic, the model fallback. Unlike providers, a missing one never makes status degraded'
        provider_status:
          anyOf:
          - $ref: '#/components/schemas/ProviderStatusOut'
          - type: 'null'
        model:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Model
          description: 'the language model plan, names only: {"primary": "anthropic" or "openai", "name" (e.g. claude-haiku-5-5), "effort" (e.g. xhigh, null for OpenAI), "backup", "speech": the provider that hears dialect clips first, "speech_backup": the one behind it, "anthropic_keys": how many Anthropic keys are in the chain, "anthropic_keys_spent": the chain positions (1 is the main key) this process found out of credit or refused in the last 10 minutes, positions only}'
        commit:
          anyOf:
          - type: string
          - type: 'null'
          title: Commit
          description: the git commit this image was built from; "unknown" outside a deploy
        credits_today:
          anyOf:
          - $ref: '#/components/schemas/CreditsTodayOut'
          - type: 'null'
          description: the global daily research ceiling and how much of it runs started today (UTC) reserved; null when the database is not up
        jobs:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Jobs
          description: 'the job runner (P4.1): {"on", "concurrency", "queued", "running", "oldest_queued_s", "done_24h", "failed_24h", "today": {kind: {"runs", "credits", "runs_cap", "credits_cap"}}}; never makes the status degraded'
        channel_connect:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Channel Connect
          description: 'connect your YouTube channel (P5.1): {"ready": true or false, "missing": the variable names it lacks (HD_GOOGLE_CLIENT_ID, HD_GOOGLE_CLIENT_SECRET, HD_TOKEN_KEY), never a value}; never makes the status degraded'
        youtube_data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Youtube Data
          description: 'the YouTube Data API and its second route (P0.9): {"state": "ok", "no_key", "key_refused", "quota_spent" or "error", "route": "data_api" or "scrapecreators", "units_today", "units_cap", "searches_today", "searches_cap", "sc_credits_today", "last_ok_at", "last_error" (a reason code)}; never makes the status degraded'
      additionalProperties: true
      type: object
      required:
      - status
      - version
      - database
      - schema
      - providers
      - provider_status
      title: HealthDeepOut
      examples:
      - database:
          latency_ms: 3.1
          state: up
          up: true
        fallback_providers:
          anthropic: true
        provider_status:
          model:
            last_success_at: '2026-09-23T10:00:00.000000+00:00'
            state: ok
          refusing: false
          search:
            accepting_runs: true
            credits_checked_at: '2026-09-23T10:00:00.000000+00:00'
            credits_left: 12000
            low: false
            low_threshold: 3500
            state: unknown
          source: how recent runs and chat turns ended
          window_minutes: 30
        providers:
          openai: true
          scrapecreators: true
        schema:
          current: true
          missing: []
        status: ok
        version: 2.1.0
    HealthOut:
      properties:
        status:
          anyOf:
          - type: string
            enum:
            - ok
            - degraded
          - type: string
          title: Status
        version:
          type: string
          title: Version
        commit:
          anyOf:
          - type: string
          - type: 'null'
          title: Commit
          description: the git commit this image was built from; "unknown" outside a deploy
        database:
          anyOf:
          - type: string
            enum:
            - up
            - busy
            - down
          - type: string
          title: Database
          description: '"busy": every pooled connection is in use; the service is loaded, not down, and status stays ok'
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
          description: when this process started (ISO 8601); a new value means a restart
        runs_in_flight:
          anyOf:
          - type: integer
          - type: 'null'
          title: Runs In Flight
          description: research runs queued or running across the service right now; null when the database did not answer. An operator restarts only at 0
      additionalProperties: true
      type: object
      required:
      - status
      - version
      - database
      title: HealthOut
      examples:
      - commit: 5d3194d0c1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6
        database: up
        runs_in_flight: 0
        started_at: '2026-09-23T16:11:02.123456+00:00'
        status: ok
        version: 2.4.0
    ProviderOut:
      properties:
        state:
          anyOf:
          - type: string
            enum:
            - ok
            - refusing
            - unknown
          - type: string
          title: State
        last_failure_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Failure At
        last_success_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Success At
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
        credits_left:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credits Left
          description: 'search only: our credits left with the search provider, from its free balance endpoint read at most every 10 minutes; null until read'
        credits_checked_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Credits Checked At
          description: 'search only: when credits_left was read (ISO 8601)'
        low:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Low
          description: 'search only: credits_left is under low_threshold (about a day of use); null until read'
        low_threshold:
          anyOf:
          - type: integer
          - type: 'null'
          title: Low Threshold
          description: 'search only: HD_SEARCH_CREDITS_LOW'
        accepting_runs:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Accepting Runs
          description: 'search only: false while the provider refuses us (HTTP 402, 401 or 403); a new run is then 503 search_unavailable, nothing reserved'
      additionalProperties: true
      type: object
      required:
      - state
      - last_failure_at
      - last_success_at
      - message
      title: ProviderOut
    ProviderStatusOut:
      properties:
        model:
          $ref: '#/components/schemas/ProviderOut'
        search:
          $ref: '#/components/schemas/ProviderOut'
        refusing:
          type: boolean
          title: Refusing
          description: true when either provider reads refusing
        window_minutes:
          type: integer
          title: Window Minutes
        source:
          type: string
          title: Source
      additionalProperties: true
      type: object
      required:
      - model
      - search
      - refusing
      - window_minutes
      - source
      title: ProviderStatusOut
    CreditsTodayOut:
      properties:
        day:
          type: string
          title: Day
          description: the UTC day, YYYY-MM-DD
        reserved:
          type: integer
          title: Reserved
          description: credits reserved by every run started this UTC day
        ceiling:
          type: integer
          title: Ceiling
          description: past this, new runs are refused with 503 at_capacity until the next UTC midnight
      additionalProperties: true
      type: object
      required:
      - day
      - reserved
      - ceiling
      title: CreditsTodayOut