> ## Documentation Index > Fetch the complete documentation index at: https://docs.hookie.ai/llms.txt > Use this file to discover all available pages before exploring further. # Ingest an event with an ingest key (PUT alias of ingestEvent) > PUT is accepted verbatim — the handler's only method check allows POST and PUT, and nothing downstream branches on the method. Not idempotent in the HTTP sense: each PUT stores a new submission unless an Idempotency-Key repeats. ## OpenAPI ````yaml /openapi.json put /v1/ingest/{ingest_key} openapi: 3.1.0 info: title: Hookie API version: 1.0.0 summary: Capture, route and deliver webhooks. description: >- Hookie exposes three HTTP surfaces. **Ingest + streaming** is the public plane. A path-form endpoint URL authenticates by its own high-entropy slug — there is no key, token or cookie — and an `ik_live_…` ingest key authenticates the `/v1/*` routes. Whenever the URL names a dataset the payload is stored whole into it; project mapping rules are evaluated on exactly one shape, `POST /v1/ingest/{ingest_key}` with no dataset segment. **The customer portal API** is a separate, token-authed surface for your end customers, scoped to one portal and one customer. **The admin API** drives the console. It accepts either a browser session or an OAuth bearer token from a connected coding agent — the same routes, the same validation, the same audit trail. An agent's authority is its user's workspace role narrowed to the scopes granted in the console. This document is generated from the request handlers and adversarially verified against them. contact: name: Hookie url: https://hookie.ai license: name: Proprietary url: https://hookie.ai/legal/terms servers: - url: https://app.hookie.ai description: Production - url: https://app.preview.hookie.ai description: Preview security: [] tags: - name: Ingest description: Send events to Hookie. - name: Streaming description: Tail events in real time over SSE or WebSocket. - name: Portal description: Token-authed surface for your end customers. - name: Projects description: Projects and their settings. - name: Routing description: Rules, endpoints, datasets and records. - name: Delivery description: Destinations, deliveries and replay. - name: Workflows description: Multi-step workflows, triggers and AI agents. - name: Observability description: Search, correlation, stats and the audit log. - name: Workspace description: Members, connected agents, SSO and billing. paths: /v1/ingest/{ingest_key}: put: tags: - Ingest summary: Ingest an event with an ingest key (PUT alias of ingestEvent) description: >- PUT is accepted verbatim — the handler's only method check allows POST and PUT, and nothing downstream branches on the method. Not idempotent in the HTTP sense: each PUT stores a new submission unless an Idempotency-Key repeats. operationId: ingestEventPut parameters: - name: ingest_key in: path required: true description: >- The plaintext ingest key (prefix lookup + constant-time SHA-256 comparison). schema: type: string - name: Idempotency-Key in: header required: false description: >- Optional; a repeat key short-circuits with 200 before quota is charged. schema: type: string - name: X-Hookie-Signature in: header required: false description: >- Required only when the key has require_signature. Format 't=,v1=', v1 = HMAC-SHA-256 over '.'. schema: type: string requestBody: required: false description: >- Identical to POST /v1/ingest/{ingest_key}: form encodings are flattened, anything else is parsed as JSON, an empty body becomes {}, and bodies over 1,000,000 bytes are rejected with 413. content: application/json: schema: description: Any JSON value. application/x-www-form-urlencoded: schema: type: object additionalProperties: oneOf: - type: string - type: array items: type: string multipart/form-data: schema: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - filename - type - size properties: filename: type: string type: type: string size: type: integer responses: '200': description: >- Idempotent replay of a submission already stored under this Idempotency-Key. content: application/json: schema: type: object required: - submission_id - idempotent additionalProperties: false properties: submission_id: type: string idempotent: type: boolean enum: - true '201': description: Stored; 'routed' holds the names of the mapping rules that applied. content: application/json: schema: type: object required: - submission_id - routed - records additionalProperties: false properties: submission_id: type: string routed: type: array items: type: string records: type: integer '400': description: >- error: 'Body must be valid JSON' or 'Body is not valid multipart/form-data'. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: >- 'Signature required' or 'Invalid signature' (signature-required keys only). content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: 'error: ''Source IP not allowed''.' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: 'error: ''Unknown ingest key''.' content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: 'error: ''Body exceeds 1000000 bytes''.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Edge rate limit (retry_after: 10) or monthly quota (upgrade_url + retry_after: 3600). content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: retry_after: type: integer upgrade_url: type: string format: uri '500': description: 'error: ''Key misconfigured'' or ''Could not store submission''.' content: application/json: schema: $ref: '#/components/schemas/Error' security: - ingestKey: [] components: schemas: Error: type: object required: - error properties: error: type: string description: Human-readable reason. retry_after: type: integer description: Seconds to wait. Present on 429. upgrade_url: type: string format: uri description: Present only on a monthly-quota 429. securitySchemes: ingestKey: type: http scheme: bearer description: >- An `ik_live_…` ingest key. Stored hashed; the plaintext is returned once at creation. ````