Implementation Deep Dive

​

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.

Authorization: Bearer YOUR_API_KEY

​

Live data payload schema

{
  "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

​

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.

​

Document ingestion

​

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

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

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"

​

List uploaded documents

• 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.

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

​

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
• 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)