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

# Implementation Deep Dive

> Build resilient integrations with the Recallio Knowledge endpoints

Use this guide when you are ready to productionize your Knowledge integration. It covers authentication, request schemas, error handling, and how to sync both structured data and documents.

## Authentication

* Every request uses bearer authentication. Add the API key you created in the dashboard under **API Keys** to the `Authorization` header.
* Keys can be rotated at any time—plan for hot swaps by storing them in your secrets manager.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Live data payload schema

`POST https://app.recallio.ai/api/Knowledge/livedata`

| Field       | Type                       | Required    | Notes                                                                                                                                      |
| ----------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`      | string                     | ✅           | Domain tag for the payload (`listing`, `resident`, `maintenance-ticket`). Use consistent values so the assistant can cluster related data. |
| `rawJson`   | object or stringified JSON | ✅           | The content you want Recallio to understand. Nested objects are supported up to 30 KB.                                                     |
| `projectId` | string                     | Recommended | Scopes the knowledge to a project/environment. Required if you want data siloed by property or deployment.                                 |
| `userId`    | string                     | Optional    | Attach the payload to a specific user for personalized recall.                                                                             |

```json theme={null}
{
  "projectId": "project_abc",
  "type": "resident",
  "userId": "resident-991",
  "rawJson": {
    "residentId": "991",
    "name": "Taylor Brooks",
    "leaseEnd": "2025-07-31",
    "preferences": {
      "pets": true,
      "parking": "garage"
    }
  }
}
```

### Delivery semantics

* The endpoint returns `202 Accepted` after the payload enters the processing queue. Most records are searchable within seconds.
* Re-sending a payload with the same identifiers inside `rawJson` acts as an upsert; the latest submission becomes the source of truth.
* Break large updates into multiple requests instead of sending a single oversized document.

### Validation errors

| Status             | Reason                                             | Suggested fix                                        |
| ------------------ | -------------------------------------------------- | ---------------------------------------------------- |
| `400 Bad Request`  | Missing `type`, invalid JSON, or payload too large | Ensure the body is valid JSON and under 30 KB.       |
| `401 Unauthorized` | Bearer token missing or invalid                    | Regenerate the API key or confirm the header casing. |

Log the response body: Recallio returns a detailed error payload when validation fails.

## Project and environment mapping

* Create projects in **Settings → Projects**. Each project exposes a unique `ProjectId`.
* Use a consistent naming convention—many teams mirror production homes or regions.
* When no `projectId` is provided, knowledge becomes globally visible across the organization. Use this for policies or team-wide playbooks.

<Callout>
  When sending data for multiple homes, call the endpoint once per project with the appropriate `projectId`. Avoid batching heterogeneous projects in a single payload.
</Callout>

## Document ingestion

Structured data is only part of the story. Upload reference PDFs (leases, SOPs, inspection reports) so assistants can cite them directly.

### Upload through the dashboard

1. Go to **Knowledge → Memory Sources**.
2. Drag-and-drop files or connect cloud storage.
3. Choose whether each file is available to the entire team or a specific project.

### Upload via API

`POST https://app.recallio.ai/api/Knowledge/document`

* Multipart form upload.
* Required field: `ProjectId`.
* Optional fields: `Tags[]`, `SourceUrl`, `SourceType`, `ConsentFlag`.

```bash theme={null}
curl https://app.recallio.ai/api/Knowledge/document \
  -H "Authorization: Bearer $RECALLIO_API_KEY" \
  -F "File=@policies.pdf" \
  -F "ProjectId=project_abc" \
  -F "Tags=policy" \
  -F "SourceUrl=https://intranet/policies/2025" \
  -F "ConsentFlag=true"
```

Recallio extracts text and metadata, then associates the document with the designated project. Processing is asynchronous; check the Memory Sources page for status.

### List uploaded documents

`GET https://app.recallio.ai/api/Knowledge/document`

* Supports pagination with `page` and `pageSize` query parameters (defaults are provided when omitted).
* Filter by `projectId` to retrieve documents scoped to a specific environment.
* Responses include filenames, tags, processing state, and the `ProjectId` you assigned on upload.

```bash theme={null}
curl "https://app.recallio.ai/api/Knowledge/document?projectId=project_abc&page=1&pageSize=50" \
  -H "Authorization: Bearer $RECALLIO_API_KEY"
```

Use the listing endpoint to power admin dashboards or reconciliation scripts that verify every project has the expected knowledge assets.

## Operational best practices

* **Idempotency**: include stable identifiers (for example `listingId`, `residentId`) inside `rawJson`. This helps you reason about updates and deletions.
* **Error monitoring**: capture non-2xx responses and alert on them. Retry `5xx` responses with exponential backoff; do not retry `4xx` without a code change.
* **Consent tracking**: if you ingest any personal data, store proof of consent and set `ConsentFlag=true` when uploading documents.
* **Schema evolution**: when adding new fields inside `rawJson`, deploy a migration in your source system first, then update Recallio to avoid missing values.

## Useful API reference links

* Full OpenAPI specification: [Recallio Swagger](https://app.recallio.ai/swagger/index.html)
* Endpoint summaries: `/api/Knowledge/livedata` and `/api/Knowledge/document` under the **SoftwareData** tag
* Related operations: `/api/Knowledge/recall` for querying stored knowledge (see API Reference tab)