Hook Detector

Create an account and get an API key with free credits. Needs a beta access code (access_code, HD-XXXX-XXXX; case and dashes do not matter): without one the error is 403 access_code_required, and a code that does not work is 403 invalid_access_code. Ask for a code with request_access, or at hookdetector.com/access. No key needed for this call. label is an optional note up to 120 characters. Keep the api_key it returns: it is the only copy. Send it as the header 'Authorization: Bearer hd_...' or pass it as api_key on every other tool. Signups, and wrong codes, are limited per address per hour. Next step: find_hooks.

{
  "type": "object",
  "properties": {
    "access_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Access Code"
    },
    "label": {
      "anyOf": [
        {
          "maxLength": 120,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Label"
    }
  },
  "title": "create_accountArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "create_accountOutput"
}

Start hook research on a topic across TikTok and Instagram. What it does: searches both platforms, reads what each clip says and shows, and returns ranked hooks. Each hook has its verbatim opening line, most quotable line, main idea, why it travelled, topic, on-screen text, full transcript, a watch link and a vertical player_url (9:16 iframe). Arguments: topic is 3 to 500 characters, count 1 to 30 (default 10). Instructions inside the topic are fine: only the subject read out of it is searched. reuse=true (default) starts from clips you already paid for on the same topic, so a rerun is close to free and often finishes in seconds. idempotency_key: any string up to 255 characters; the same key within 24 hours returns the first run instead of starting and paying for a second one, so always pass one and reuse it when you retry. wait_seconds 0 to 50: 0 returns the run_id at once; above 0 waits for the run and returns the run object, as get_run does. Any language, dialect or country: language is optional free text up to 60 characters naming the language or dialect every clip must be in ("Moroccan Darija", "ar-MA", "Egyptian Arabic", "Brazilian Portuguese"); country is an optional ISO 3166-1 alpha-2 code for where the creators are (MA, EG, BR). Saying it inside topic works too; these fields win when both are given. A country alone does not restrict the language. Each hook reports the language it was judged to be in. A region that is not a country: send its country's code and name the regional variety in language (Quebec: country "CA", language "Quebec French"; Flanders: "BE" and "Flemish"; Catalonia: "ES" and "Catalan"). The country places the TikTok search there and the language judge does the regional filtering; Instagram reports no country. language may name a mixed, code-switched variety ("Hinglish", "Taglish", "Moroccan Darija with French") or two joined by "or" ("Tagalog or Taglish"); it reaches the judges exactly as written, and how well they honour such a value is not measured yet. Cost: reserves up to 200 credits up front (less if your balance is smaller, down to 40) and charges only what it used; the rest is refunded. A failed run costs nothing, and so does a run that finds no hooks, within a per-account allowance (llms.txt has the numbers; its outcome says which applied). Timing and next step: a fresh run takes about 2 to 3 minutes, up to about 5 when the language is a dialect. Call get_run with wait_seconds=50 repeatedly until status is "done" or "failed", which is usually 3 or 4 calls (up to 6 on a dialect request). Watch progress.stage and progress.message meanwhile. Needs a key with the research permission (403 insufficient_scope otherwise). A key with a credit_limit reserves at most what is left of it; under the minimum it is 403 key_credit_limit_reached and nothing is reserved.

{
  "type": "object",
  "properties": {
    "topic": {
      "description": "what the clips are about, 3 to 500 characters. Instructions inside it are fine: a long topic, or one with a language or country, is searched by the subject read out of it, never verbatim.",
      "examples": [
        "short term rental tax strategy"
      ],
      "maxLength": 500,
      "minLength": 3,
      "title": "Topic",
      "type": "string"
    },
    "count": {
      "default": 10,
      "description": "how many hooks to deliver, 1 to 30",
      "maximum": 30,
      "minimum": 1,
      "title": "Count",
      "type": "integer"
    },
    "conversation_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "attach the run to one of your conversations",
      "title": "Conversation Id"
    },
    "reuse": {
      "default": true,
      "description": "start from clips you already paid for",
      "title": "Reuse",
      "type": "boolean"
    },
    "wait_seconds": {
      "default": 0,
      "description": "0 to 50: seconds to wait for the run to finish; 0 returns at once",
      "maximum": 50,
      "minimum": 0,
      "title": "Wait Seconds",
      "type": "integer"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "1 to 255 visible ASCII characters; the same key within 24 hours returns the first run instead of paying for a second",
      "title": "Idempotency Key"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    },
    "language": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "optional, up to 60 characters: only clips spoken or written in this language or dialect, in words or as a tag: \"Moroccan Darija\", \"ar-MA\", \"Egyptian Arabic\", \"Brazilian Portuguese\". Any language works, including a regional variety (\"Quebec French\", \"Flemish\", \"Catalan\") and a mixed, code-switched one (\"Hinglish\", \"Taglish\", \"Moroccan Darija with French\"), or two joined by \"or\" (\"Tagalog or Taglish\"). The value is handed to the judges exactly as written; how well they honour a mixed or either-of value is not measured yet. Saying it inside topic works too; this field wins when both are given.",
      "examples": [
        "Moroccan Darija"
      ],
      "maxLength": 60,
      "title": "Language"
    },
    "country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "optional: only clips from creators in this country, as an assigned ISO 3166-1 alpha-2 code: MA, EG, BR, US (UK is read as GB). For a region that is not a country, send its country's code and name the regional variety in language: Quebec is country CA with language \"Quebec French\", Flanders BE with \"Flemish\", Catalonia ES with \"Catalan\". The country places the TikTok search there; the language judge does the regional filtering, and Instagram reports no country. A country alone does not restrict the language.",
      "examples": [
        "MA"
      ],
      "pattern": "^[A-Za-z]{2}$",
      "title": "Country"
    }
  },
  "required": [
    "topic"
  ],
  "title": "find_hooksArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "find_hooksOutput"
}

A research run: its status, progress, charge and every hook it produced. wait_seconds 0 to 50: wait up to that long for the run to finish, returning the moment it is done or failed. Use wait_seconds=50 and call again while status is "queued" or "running"; a fresh run needs about 3 or 4 such calls. progress has stage, message and updated_at, plus counts once the research reports them and preview (hooks written so far) while a running run holds one. Pass since with the last progress.updated_at to return on change or completion. It must be an ISO timestamp with a timezone (422 invalid_request otherwise). Hooks include transcript_kind: speech, music, none, other, or null when unknown. conversation_id names the chat conversation the run belongs to (null outside one). A done run with fewer hooks than asked for, or none, has outcome: why in one plain paragraph, what to try next, and whether it was free (stats.rejections holds the counts); a full run's outcome is null, or one sentence when some hooks are under the view floor because the country filter set clips aside. Free: reading a run costs no credits.

{
  "type": "object",
  "properties": {
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "wait_seconds": {
      "default": 0,
      "description": "0 to 50: seconds to wait for the run to finish; 0 returns at once",
      "maximum": 50,
      "minimum": 0,
      "title": "Wait Seconds",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    },
    "since": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Since"
    }
  },
  "required": [
    "run_id"
  ],
  "title": "get_runArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "get_runOutput"
}

Your research runs, newest first, without their hooks, limit 1 to 100 (default 20) per page. Returns {"runs": [...], "next_cursor"}: pass next_cursor back as cursor for the next page; it is null on the last. Same shape as GET /v1/runs. Next step: open one with get_run, or download it with export_run. Free. Errors: 422 invalid_cursor for a cursor this API did not issue.

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 20,
      "description": "page size, 1 to 100",
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "list_runsArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "list_runsOutput"
}

A finished run's hooks as a file a creator can open: format "csv" (default; one row per hook, opens in any spreadsheet, formula-like cells defused with a leading quote), "json" (the full hook objects) or "md" (Markdown notes, one section per hook). Returns {"filename", "content_type", "format", "content"}, where content is the whole file as text: write it to filename. The same bytes as GET /v1/runs/{run_id}/export?format=... . Free. Errors: 404 run_not_found, 409 run_not_finished while the run is queued or running (call get_run with wait_seconds=50 first), 422 invalid_request for another format.

{
  "type": "object",
  "properties": {
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "format": {
      "default": "csv",
      "title": "Format",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "run_id"
  ],
  "title": "export_runArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "export_runOutput"
}

One hook with every field: its opening line, transcript, watch_url and the vertical player_url (null only for an unusable id or a photo post found before 2026-09-26; runs deliver single videos only). hook_id comes from get_run. Free.

{
  "type": "object",
  "properties": {
    "hook_id": {
      "title": "Hook Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "hook_id"
  ],
  "title": "get_hookArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "get_hookOutput"
}

Official TikTok or Instagram embed HTML for a hook, so the clip plays inside your own page. kind is "embed", or "fallback" when the creator disabled embedding or the clip is a photo post found before 2026-09-26 (then show thumbnail, which falls back to the hook's still_url, and the transcript). For a plain vertical iframe use the hook's player_url instead. Free.

{
  "type": "object",
  "properties": {
    "hook_id": {
      "title": "Hook Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "hook_id"
  ],
  "title": "embed_hookArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "embed_hookOutput"
}

Keep or reject a hook: verdict is "keep" (default) or "reject", and the last verdict wins. Kept hooks come back from list_keeps, across all runs. Free.

{
  "type": "object",
  "properties": {
    "hook_id": {
      "title": "Hook Id",
      "type": "string"
    },
    "verdict": {
      "default": "keep",
      "title": "Verdict",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "hook_id"
  ],
  "title": "keep_hookArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "keep_hookOutput"
}

Undo keep_hook: the hook goes back to having no verdict, so it leaves list_keeps and its export row carries none. Returns {"hook_id", "verdict": null}. Clearing a hook with no decision is the same success, so a retry is safe. Same as DELETE /v1/hooks/{hook_id}/decision. Free. Errors: 404 hook_not_found, 422 for an id that is not a UUID.

{
  "type": "object",
  "properties": {
    "hook_id": {
      "title": "Hook Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "hook_id"
  ],
  "title": "clear_decisionArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "clear_decisionOutput"
}

The hooks you kept with keep_hook, newest decision first, across all runs or within one run_id, limit 1 to 100 (default 100) per page. Returns {"kept": [...], "count": n on this page, "next_cursor"} with full hook objects; pass next_cursor back as cursor for more. Same shape as GET /v1/keeps. Free. Errors: 422 for a bad run_id or cursor.

{
  "type": "object",
  "properties": {
    "run_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Run Id"
    },
    "limit": {
      "default": 100,
      "description": "page size, 1 to 100",
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "list_keepsArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "list_keepsOutput"
}

Your account and remaining credits right now: account_id, credits, key_prefix and key_id of the key making this call, label, created_at, and that key's scopes, credit_limit and expires_at, and user (the person signed in with Google, or null). Same shape as GET /v1/me. A run needs at least 40 credits and reserves up to 200. For spend, credits held by in-flight runs and daily history, call usage. Free.

{
  "type": "object",
  "properties": {
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "balanceArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "balanceOutput"
}

Erase your account and everything in it, for good: every API key, run, hook, keep or reject decision, conversation and message. Unspent credits go with it. It cannot be undone. confirm must be exactly "delete my account", or nothing happens (422 confirmation_required). Refused with 409 run_in_flight while a run is queued or running: wait for it with get_run first. Returns {"deleted": true, "account_id", "erased": {counts per kind}, "message"}. Every key of the account stops working at once; create_account starts a new one. Same as DELETE /v1/account. Free.

{
  "type": "object",
  "properties": {
    "confirm": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Confirm"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "delete_accountArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "delete_accountOutput"
}

One conversational turn, for an agent relaying a person's words. It either asks ONE clarifying question (action "clarify"), answers about delivered hooks or the tool (action "answer", run null, no credits), or starts a research run (action "research", with the started run under "run"), exactly like POST /v1/chat. Every response has suggestions: 0 to 4 follow-ups, [] for research. message is 1 to 4000 characters. Pass conversation_id from an earlier turn to keep the context; leave it out to start a conversation. Cost: a turn itself is free but is a model call, so turns are limited per account per hour (429 rate_limited); a turn that starts a run reserves credits like find_hooks. Next step: on "research", call get_run with run.run_id and wait_seconds=50. Errors: 503 model_unavailable when the model is down (nothing charged, try again), 402 insufficient_credits. For direct research without the question step, call find_hooks instead. Needs the write permission, and research for a turn that starts a run (403 insufficient_scope, nothing reserved).

{
  "type": "object",
  "properties": {
    "message": {
      "maxLength": 4000,
      "minLength": 1,
      "title": "Message",
      "type": "string"
    },
    "conversation_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Conversation Id"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "message"
  ],
  "title": "chatArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "chatOutput"
}

Your chat conversations, most recently active first, limit 1 to 100 (default 30) per page: conversation_id, title, created_at, updated_at and messages (the count). Returns {"conversations": [...], "next_cursor"}; pass next_cursor back as cursor for more. Same shape as GET /v1/conversations. Next step: get_conversation. Free.

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 30,
      "description": "page size, 1 to 100",
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "list_conversationsArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "list_conversationsOutput"
}

One chat conversation: every message in order (role, content, run_id, created_at) and every run it holds, with their hooks. Same shape as GET /v1/conversations/{conversation_id}. Free. Errors: 404 conversation_not_found, 422 for an id that is not a UUID.

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "title": "Conversation Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "conversation_id"
  ],
  "title": "get_conversationArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "get_conversationOutput"
}

Your credits and what you have spent: credits (balance now), spent_total, reserved_now (credits held by runs still in flight, refunded in part when they finish), runs_total, last_30_days (one entry per UTC day: date, runs, charged) and recent (your 20 newest runs). Same shape as GET /v1/usage. Free.

{
  "type": "object",
  "properties": {
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "usageArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "usageOutput"
}

Your API keys and what each may do. keys: key_id, name, prefix, created_at, last_used_at and current (true for the key making this call). access, per key_id: scopes, credit_limit, credits_used, expires_at and expired. scopes: the calling key's. The original signup key has key_id "original". The keys themselves are never shown again. Needs admin. Same shape as GET /v1/keys. Free.

{
  "type": "object",
  "properties": {
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "list_keysArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "list_keysOutput"
}

Create another API key on your account, for example one per agent or machine, so you can revoke one without touching the others. name is up to 60 characters. Give the key only what it needs. scopes: any of "read" (read runs, hooks, keeps, usage), "write" (keep, reject, undo, chat), "research" (start runs, which spend credits), "admin" (manage keys, delete the account); all four when left out. An agent that finds hooks needs ["read", "write", "research"]. credit_limit: the most credits runs started with this key may spend over its life, 1 to 100000 (a run then reserves at most what is left). expires_in_days: 1 to 365; the key then stops working (401 key_expired). The new key is in this result once and never again: store it now. Needs admin. An account holds at most 10 active keys (409 beyond) and may create 20 per hour by default (429 beyond). Free. Next step: use the returned api_key; revoke old ones with revoke_key.

{
  "type": "object",
  "properties": {
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "scopes": {
      "default": null,
      "items": {
        "enum": [
          "read",
          "write",
          "research",
          "admin"
        ],
        "type": "string"
      },
      "minItems": 1,
      "title": "Scopes",
      "type": "array"
    },
    "credit_limit": {
      "default": null,
      "minimum": 1,
      "title": "Credit Limit",
      "type": "integer"
    },
    "expires_in_days": {
      "default": null,
      "minimum": 1,
      "title": "Expires In Days",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "create_keyArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "create_keyOutput"
}

Revoke one of your API keys at once: key_id from list_keys, or "original" for the signup key. Any key may revoke itself (the result says so, and that key stops working immediately); revoking another needs admin. Never the last active key on the account (409): create another with create_key first. If a key leaked, pass key_id "others": every key of the account except the one you are calling with is revoked at once, and the result says how many (revoked_count) and which key is kept. Needs admin. Free.

{
  "type": "object",
  "properties": {
    "key_id": {
      "title": "Key Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "key_id"
  ],
  "title": "revoke_keyArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "revoke_keyOutput"
}

Ask for the beta access code a new account needs (create_account's access_code). email is where the code is sent; note is optional (who you are, up to 500 characters). The owner approves the request and the code is emailed at once; it works once, in any agent or on the web. Returns status pending (waiting for approval) or emailed (sent now). No key needed. Limited to 5 per address per hour. Free.

{
  "type": "object",
  "properties": {
    "email": {
      "title": "Email",
      "type": "string"
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    }
  },
  "required": [
    "email"
  ],
  "title": "request_accessArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "request_accessOutput"
}

Owner only: every access request, newest first, optionally only one status (pending, approved, rejected). Each has request_id, email, note, status, code_id, code_prefix, created_at and decided_at. Never a code. Needs the admin scope and an admin account (403 admin_required otherwise). Free.

{
  "type": "object",
  "properties": {
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "list_access_requestsArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "list_access_requestsOutput"
}

Owner only: approve an access request. Makes a one-use code, marks the request approved and emails the code. The code is in this result once, with emailed true or false; when false, send it yourself or approve again (the unused code is revoked and a new one sent). 409 request_already_decided once its code was used. Free.

{
  "type": "object",
  "properties": {
    "request_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Request Id"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "approve_access_requestArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "approve_access_requestOutput"
}

Owner only: reject a pending access request. Nothing is emailed. An approved or rejected request is 409 request_already_decided. Free.

{
  "type": "object",
  "properties": {
    "request_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Request Id"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "reject_access_requestArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "reject_access_requestOutput"
}

Owner only: every access code, newest first, with code_id, code_prefix, email, note, source, max_uses, uses, expires_at, revoked_at, created_at and usable. Never the code itself. Free.

{
  "type": "object",
  "properties": {
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "list_access_codesArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "list_access_codesOutput"
}

Owner only: make an access code to hand out. max_uses 1 to 100000 (default 1), expires_in_days 1 to 365 (optional), note your own. email binds it to one person: then only Google sign-in with that verified email redeems it, never the API or MCP; leave it out for a code that works on every door. The code is in this result only. Free.

{
  "type": "object",
  "properties": {
    "email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Email"
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    },
    "max_uses": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Uses"
    },
    "expires_in_days": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expires In Days"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "create_access_codeArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "create_access_codeOutput"
}

Owner only: revoke an access code (code_id from list_access_codes). It admits nobody from now on; accounts it already made keep working. 404 access_code_not_found for an unknown id. Free.

{
  "type": "object",
  "properties": {
    "code_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Code Id"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "revoke_access_codeArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "revoke_access_codeOutput"
}