> ## 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. # Suggest a dataset and field mappings for a sample payload ## OpenAPI ````yaml /openapi.json post /admin/api/ai/suggest-mapping 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: /admin/api/ai/suggest-mapping: post: tags: - AI summary: Suggest a dataset and field mappings for a sample payload operationId: suggestMapping requestBody: required: true content: application/json: schema: type: object required: - sample properties: sample: description: >- A sample payload — any JSON value except null. Objects are stringified; the text is truncated to 6000 characters before the model sees it. hint: type: string description: >- Free-text context. Also used as the fallback dataset name when the model's suggestion is not a valid identifier. responses: '200': description: >- Advisory only — nothing is created. The model's output is normalized and hard-bounded here (keys coerced to unique snake_case, at most 50 mappings and 20 conditions, paths truncated to 200 chars) and still re-validated when the caller actually creates the rule or webhook. content: application/json: schema: type: object required: - dataset - mappings - conditions properties: dataset: type: string description: Falls back to the hint, then to 'events'. mappings: type: array maxItems: 50 items: type: object required: - path - key properties: path: type: string description: Dot/bracket path into the sample, e.g. user.email. key: type: string description: >- Flat snake_case key to store it as; unique within the response. conditions: type: array maxItems: 20 items: type: object required: - path - equals properties: path: type: string equals: type: string maxLength: 500 description: >- Equality-only, matching the routing-rule condition shape. Paths beginning with '$' are dropped. '400': description: >- `sample is required` — body missing, unparseable, or `sample` null/absent. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not signed in. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- `Insufficient role` — write capability required (checked before the action is even matched), or `Missing X-Requested-With header`. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- `Unknown AI action` — any path under /admin/api/ai other than POST suggest-mapping. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: '`Internal error`.' content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: '`AI suggestion unavailable` — the Workers AI call threw.' content: application/json: schema: $ref: '#/components/schemas/Error' security: - session: [] - bearerAuth: [] 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: session: type: apiKey in: cookie name: hookie_session description: >- The console's sealed session cookie, set by WorkOS AuthKit. Mutating requests also require the `X-Requested-With` CSRF header. bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- An OAuth 2.1 access token from a connected agent, audienced at the `/mcp` resource URI. The agent acts as its user, with that user's role narrowed to the granted `hookie:*` scopes. No CSRF header is required — a bearer token is not ambient credentials. ````