> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vrin.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Insert

> Insert text content into the knowledge base

Insert text content into Vrin. The content is chunked, facts are extracted (entities, relationships, attributes), and everything is indexed for retrieval.

Insertion is **asynchronous** -- the endpoint returns a `job_id` immediately and processes in the background.

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer vrin_live_abc123`
</ParamField>

<ParamField body="content" type="string" required>
  Text content to insert.
</ParamField>

<ParamField body="title" type="string" default="Untitled">
  Document title for search results and source attribution.
</ParamField>

<ParamField body="tags" type="string[]" default="[]">
  Tags for categorization.
</ParamField>

<ParamField body="metadata" type="object" default="{}">
  Arbitrary metadata attached to the document.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "job_id": "job_abc123",
    "message": "Content queued for processing"
  }
  ```
</ResponseExample>

### Job status polling

After receiving the `job_id`, poll the status endpoint:

```
GET /job-status/{job_id}
```

<ResponseExample>
  ```json 200 theme={null}
  {
    "job_id": "job_abc123",
    "status": "extracting",
    "progress": 0.65,
    "message": "Extracting facts from chunks..."
  }
  ```
</ResponseExample>

### Job status values

| Status       | Description                             |
| ------------ | --------------------------------------- |
| `pending`    | Job is queued                           |
| `chunking`   | Splitting content into chunks           |
| `extracting` | Extracting facts with LLM               |
| `storing`    | Writing to graph + vector store         |
| `completed`  | Processing finished successfully        |
| `failed`     | Processing failed (see `error_details`) |

### Completed job

<ResponseExample>
  ```json 200 theme={null}
  {
    "job_id": "job_abc123",
    "status": "completed",
    "progress": 1.0,
    "data": {
      "facts_extracted": 18,
      "chunks_created": 3,
      "document_id": "doc_xyz"
    }
  }
  ```
</ResponseExample>

### SDK usage

The Python SDK handles polling automatically:

```python theme={null}
# Synchronous (waits for completion)
result = client.insert("content...", title="My Document")

# Asynchronous (returns job_id)
job_id = client.insert("content...", wait=False)
status = client.get_job_status(job_id)
```