> ## 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 straight into a named dataset > Same pipeline as ingestEvent but with identity routing into {dataset}. PUT is accepted identically (ingestEventToDatasetPut); any other method returns 405 {"error":"Use POST"}. ## OpenAPI ````yaml /openapi.json post /v1/ingest/{ingest_key}/{dataset} 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}/{dataset}: post: tags: - Ingest summary: Ingest an event with an ingest key straight into a named dataset description: >- Same pipeline as ingestEvent but with identity routing into {dataset}. PUT is accepted identically (ingestEventToDatasetPut); any other method returns 405 {"error":"Use POST"}. operationId: ingestEventToDataset parameters: - name: ingest_key in: path required: true description: >- The plaintext ingest key (prefix lookup + constant-time SHA-256 comparison; revoked keys never match). schema: type: string - name: dataset in: path required: true description: >- Dataset name. Its presence switches routing to identity: the whole payload is stored as one record in this dataset and the project's mapping rules are NOT consulted. The name is used as given (no validation, no lookup) and it overrides the key's dataset_default. 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: >- Form encodings are flattened (repeats become arrays, file parts become {filename, type, size} with the bytes discarded); every other Content-Type is parsed as JSON; an empty body becomes {}. On this route a payload that is not a JSON object (array or scalar) is wrapped as {"value": } before it is stored. Over 1,000,000 bytes yields 413. content: application/json: schema: description: >- Any JSON value; objects are stored field-for-field, arrays and scalars are wrapped as {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 — a submission with this Idempotency-Key already exists for the tenant. No quota is charged when the duplicate is detected up front; a request that loses the unique-index race has already been counted against the monthly quota. 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 and identity-routed; 'routed' is the single-element array holding {dataset}. A swallowed routing failure surfaces as routed: [] and records: 0. 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 keys only: 'Signature required' or 'Invalid signature'. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- error: 'Source IP not allowed' — key allowlist AND tenant allowlist must both match. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- error: 'Unknown ingest key' — unknown/revoked key, hash mismatch, or missing tenant row. An unknown dataset name is NOT a 404; the dataset is created implicitly by the write. 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 {error: 'Rate limit exceeded', retry_after: 10} or monthly quota {error: 'Monthly event quota exceeded', upgrade_url: '/settings/billing', retry_after: 3600}. No Retry-After header. 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. ````