# Ingest events (/docs/api/ingest)
<EndpointLayout>
<EndpointHeader method="POST" path="/v1/dock/ingest" />

Every write goes through this endpoint. Declare a `container`, a `memory_space_id`, or both, and each event is routed by what you declare. `dock.flush` calls it for you.

<EndpointExamples>
<CodeTabs>
  <Tab value="cURL">
    ```bash
    curl https://api.docklee.com/v1/dock/ingest \
      -H "Authorization: Bearer $DOCKLEE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "memory_space_id": "your-memory-space-id",
        "events": [
          {
            "content": "Maya prefers email over phone calls.",
            "type": "preference",
            "end_user": "user_8f2c"
          }
        ]
      }'
    ```
  </Tab>
  <Tab value="Python">
    ```python
    from docklee import Dock

    dock = Dock(memory_space_id="your-memory-space-id")
    dock.capture("Maya prefers email over phone calls.", type="preference", end_user="user_8f2c")
    result = dock.flush_sync()
    ```
  </Tab>
  <Tab value="TypeScript">
    ```ts
    import { Dock } from 'docklee';

    const dock = new Dock({ memorySpaceId: 'your-memory-space-id' });
    dock.capture('Maya prefers email over phone calls.', { type: 'preference', endUser: 'user_8f2c' });
    const result = await dock.flush();
    ```
  </Tab>
</CodeTabs>

<Tabs items={['200', '207', '422']}>
  <Tab value="200">
    ```json
    {
      "batch_id": "3f6d2a1c-8b4e-4c2f-9a71-5e0b9c4d7a12",
      "accepted": 1,
      "rejected": 0,
      "errors": [],
      "usage": {
        "events_accepted": 1,
        "ke_events": 0,
        "dum_events": 1,
        "processing_time_ms": 412
      }
    }
    ```
  </Tab>
  <Tab value="207">
    ```json
    {
      "batch_id": "8c2e4f1a-6b7d-4e93-a5c0-2d9f1b3e7a64",
      "accepted": 1,
      "rejected": 1,
      "errors": [
        {
          "index": 1,
          "error": "duplicate_event",
          "message": "Event deduplicated (identical content within 60s window)"
        }
      ],
      "usage": {
        "events_accepted": 1,
        "ke_events": 0,
        "dum_events": 1,
        "processing_time_ms": 389
      }
    }
    ```
  </Tab>
  <Tab value="422">
    ```json
    {
      "error": "missing_destination",
      "message": "At least one of container or memory_space_id must be provided.",
      "batch_id": "5a9c1e7f-3d24-4b8a-9e60-c1f7a2d48b3e"
    }
    ```
  </Tab>
</Tabs>
</EndpointExamples>

## Body [#body]

<ApiFields>
  <ApiField name="events" type="object[]" required>
    The events to write, from 1 to 100.
  </ApiField>
  <ApiField name="events[].content" type="string" required>
    The text to store, up to 50,000 characters.
  </ApiField>
  <ApiField name="events[].type" type="string" required>
    One of `conversation`, `document`, `event`, `preference`, `entity`, or `knowledge`. Decides where the event goes when you declare both destinations.
  </ApiField>
  <ApiField name="events[].metadata" type="object | null">
    Your own key and value pairs, up to 10 KB.
  </ApiField>
  <ApiField name="events[].end_user" type="string">
    The person a memory belongs to. See [End users](/docs/docklee/end-users).
  </ApiField>
  <ApiField name="events[].dedup_key" type="string | null">
    Your own key, up to 256 characters, for deciding when two events are the same.
  </ApiField>
  <ApiField name="events[].timestamp" type="string<date-time> | null">
    When the event happened, in ISO 8601. Defaults to the time Docklee receives it.
  </ApiField>
  <ApiField name="container" type="string | null">
    `vector` or `okf`. The knowledge container to write to. See [Containers](/docs/docklee/containers).
  </ApiField>
  <ApiField name="dimension" type="integer | null">
    The vector dimension, for `container: "vector"` only. Leave it out to use your workspace default.
  </ApiField>
  <ApiField name="memory_space_id" type="string<uuid> | null">
    The memory space to write to.
  </ApiField>
</ApiFields>

Declare at least one of `container` and `memory_space_id`.

## Routing [#routing]

| You declare | Where events go |
| --- | --- |
| `container` only | Every event goes to the container. |
| `memory_space_id` only | Every event goes to the memory space. |
| Both | `document` and `knowledge` events go to the container. The rest go to the memory space. |

## Response [#response]

<ApiFields>
  <ApiField name="batch_id" type="string<uuid>" required>
    The ID of this batch. Quote it to support.
  </ApiField>
  <ApiField name="accepted" type="integer" required>
    Events stored.
  </ApiField>
  <ApiField name="rejected" type="integer" required>
    Events not stored.
  </ApiField>
  <ApiField name="errors" type="object[]" required>
    One entry per rejected event, with its `index`, an `error` code, and a `message`. See [Errors](/docs/api/errors#per-event-errors).
  </ApiField>
  <ApiField name="usage" type="object" required>
    `events_accepted`, `ke_events`, `dum_events`, and `processing_time_ms` for this batch.
  </ApiField>
</ApiFields>

## Status codes [#status-codes]

| Status | Meaning |
| --- | --- |
| `200` | Every event was accepted. |
| `207` | Some events were accepted and some were rejected. |
| `400` | The `memory_space_id` isn't a valid UUID. |
| `401` | The key is missing, malformed, or revoked. |
| `403` | The key can't write here, such as `ke_runtime_denied` for a container write without the Knowledge Engines runtime. |
| `404` | The memory space doesn't exist in the key's workspace. |
| `413` | The body is too large. |
| `422` | No destination was declared, a field is invalid, or every event was rejected. |
| `429` | The write rate limit was hit. |
</EndpointLayout>
