Skip to main content
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.
Authorization: Bearer YOUR_API_KEY

​
Live data payload schema

POST https://app.recallio.ai/api/Knowledge/livedata
FieldTypeRequiredNotes
typestring✅Domain tag for the payload (listing, resident, maintenance-ticket). Use consistent values so the assistant can cluster related data.
rawJsonobject or stringified JSON✅The content you want Recallio to understand. Nested objects are supported up to 30 KB.
projectIdstringRecommendedScopes the knowledge to a project/environment. Required if you want data siloed by property or deployment.
userIdstringOptionalAttach the payload to a specific user for personalized recall.
 
{
  "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

StatusReasonSuggested fix
400 Bad RequestMissing type, invalid JSON, or payload too largeEnsure the body is valid JSON and under 30 KB.
401 UnauthorizedBearer token missing or invalidRegenerate 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.
When sending data for multiple homes, call the endpoint once per project with the appropriate projectId. Avoid batching heterogeneous projects in a single payload.

​
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.
curl https://app.recallio.ai/api/Knowledge/document \
  -H "Authorization: Bearer $RECALLIO_API_KEY" \
  -F "[email protected]" \
  -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.
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.
  • 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)