Every endpoint of the CortexPlus REST API, generated from the published OpenAPI specification. Field descriptions come straight from the spec, in English.
All endpoints live under https://api.cortexplus.io and accept and return JSON. Request bodies are limited to 1 MB, except audio and image uploads.
Send your key as Authorization: Bearer cortex_.... Create one in API keys. Endpoints marked no auth are used to create an account or sign in.
curl -sS https://api.cortexplus.io/v1/auth/me \
-H 'authorization: Bearer cortex_...'Check known file hashes before uploading, then create a signed upload and save the uploaded file as a memory.
POST /v1/uploads/known accepts 1–500 lowercase hexadecimal SHA-256 hashes matching ^[0-9a-f]{64}$. It returns { "known": [{ "sha256", "nodeId" }] }; hashes already in the account do not need to be uploaded again.
POST /v1/uploads accepts { "name", "contentType", "size" }. The optional size is the exact file size in bytes. The response includes key, uploadUrl, and expiresIn for the signed PUT.
If the supplied size exceeds the plan limit, the request is rejected before signing with HTTP 413 and { "error": "upload_too_large", "resource": "uploadMaxBytes", "requested", "limit" }. When you send size, the PUT must use that exact Content-Length.
The per-file limit is 500 MB on Free and 10 GB on paid plans.
POST /v1/memories accepts { "key", "sha256", "contentType", "name", "tags" }. The optional sha256 is lowercase hexadecimal and lets CortexPlus deduplicate repeated photos and videos per user. The response has "duplicate": true when the content already existed, so nothing is counted twice.
GET /v1/usage returns plan quotas, including quotas.uploadMaxBytes.
curl -sS https://api.cortexplus.io/v1/uploads/known \
-H 'authorization: Bearer $CORTEX_API_KEY' \
-H 'content-type: application/json' \
-d '{"hashes":["'"$SHA256"'"]}'upload=$(curl -sS https://api.cortexplus.io/v1/uploads \
-H 'authorization: Bearer $CORTEX_API_KEY' \
-H 'content-type: application/json' \
-d "{\"name\":\"$FILE_NAME\",\"contentType\":\"$CONTENT_TYPE\",\"size\":$SIZE}")
KEY=$(printf '%s' "$upload" | jq -r '.key')
url=$(printf '%s' "$upload" | jq -r '.uploadUrl')
curl -sS -X PUT "$url" -H "Content-Type: $CONTENT_TYPE" --upload-file "$FILE"curl -sS https://api.cortexplus.io/v1/memories \
-H 'authorization: Bearer $CORTEX_API_KEY' \
-H 'content-type: application/json' \
-d "{\"key\":\"$KEY\",\"sha256\":\"$SHA256\",\"contentType\":\"$CONTENT_TYPE\",\"name\":\"$FILE_NAME\",\"tags\":[]}"/v1/signup No authCreate an account or begin signing in. CortexPlus sends a 6-digit code by email; use the connect operation with that code and the email next.
| Name | Type | Description |
|---|---|---|
| email * | string (email) | Email address for the CortexPlus account. |
| name | string | |
| client | string | Name of the AI platform requesting the connection. |
202 Successful response.
| Name | Type | Description |
|---|---|---|
| sent * | boolean |
/v1/connect No authRedeem the 6-digit code received by email. Save the returned apiKey in the connector configuration.
| Name | Type | Description |
|---|---|---|
| email * | string (email) | Email the code was sent to. |
| key * | string | 6-digit code received by email. |
| client | string | Name of the AI platform requesting the connection. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| apiKey * | string | |
| email * | string | |
| name * | string |
/v1/auth/register No authCreate a CortexPlus account. A 6-digit code is emailed and the account stays pending (202) until it is confirmed with /v1/auth/verify. When verification is disabled the response is a device session (201).
| Name | Type | Description |
|---|---|---|
| email * | string (email) | |
| name | string | |
| password * | string | 8–∞ chars |
| deviceName | string | |
| platform | string |
201 Successful response.
| Name | Type | Description |
|---|---|---|
| deviceToken * | string | Device credential (cxd_…); use it as the bearer token. |
| user * | object |
202 Successful response.
| Name | Type | Description |
|---|---|---|
| verificationRequired * | true | |
| email * | string |
/v1/auth/login No authLog in with email and password and issue a device token for this app install.
| Name | Type | Description |
|---|---|---|
| email * | string (email) | |
| password * | string | |
| deviceName | string | |
| platform | string |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| deviceToken * | string | Device credential (cxd_…); use it as the bearer token. |
| user * | object |
403 Request failed.
| Name | Type | Description |
|---|---|---|
| error * | string | |
| field | string |
/v1/auth/verify No authConfirm the email with the 6-digit code sent at signup and issue a device token for this app install.
| Name | Type | Description |
|---|---|---|
| email * | string (email) | |
| code * | string | 6-digit code received by email. |
| deviceName | string | |
| platform | string |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| deviceToken * | string | Device credential (cxd_…); use it as the bearer token. |
| user * | object |
/v1/auth/verify/resend No authEmail a new verification code to a pending account. Requires the signup password.
| Name | Type | Description |
|---|---|---|
| email * | string (email) | |
| password * | string | Password chosen at signup. |
202 Successful response.
| Name | Type | Description |
|---|---|---|
| sent * | boolean |
/v1/auth/key No authSend a 6-digit sign-in code to the account email address.
| Name | Type | Description |
|---|---|---|
| email * | string (email) |
202 Successful response.
| Name | Type | Description |
|---|---|---|
| sent * | boolean | |
| expiresInMinutes * | integer |
/v1/auth/key/redeem No authRedeem the 6-digit code received by email (with the same email) and issue a device token for this app install.
| Name | Type | Description |
|---|---|---|
| email * | string (email) | Email the code was sent to. |
| key * | string | 6-digit code received by email. |
| deviceName | string | |
| platform | string |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| deviceToken * | string | Device credential (cxd_…); use it as the bearer token. |
| user * | object |
/v1/auth/me Bearer keyReturn the account behind the presented credential.
200 Successful response.
/v1/auth/me Bearer keyUpdate the account display name and/or language, timezone, geolocation and health agent access settings.
| Name | Type | Description |
|---|---|---|
| name | string | 1–100 chars |
| settings | object | |
| settings.language | "pt-BR" | "en" | "es" | |
| settings.timezone | string | 1–∞ chars |
| settings.geolocation | boolean | Record location sent with memory captures. · default true |
| settings.healthAgentAccess | boolean | Share health (`saude`) memories with AI assistants using API keys (MCP and integrations). · default false |
| settings.birthDate | string | null (date) | Birth date used for nutrition intake ranges; `null` clears it. |
| settings.sex | "male" | "female" | null | Biological sex used for nutrition intake ranges; `null` clears it. |
| settings.activityLevel | "sedentary" | "light" | "moderate" | "active" | null | Physical activity level used for the estimated energy requirement. |
200 Successful response.
/v1/auth/me Bearer keyPermanently delete the account and all associated data.
| Name | Type | Description |
|---|---|---|
| email * | string |
204 Account deleted.
/v1/auth/password Bearer keySet a password on a passwordless account, or change it when currentPassword is provided. Other device tokens are revoked.
| Name | Type | Description |
|---|---|---|
| newPassword * | string | 8–∞ chars |
| currentPassword | string | Required when the account already has a password. |
204 Password updated.
/v1/auth/devices Bearer keyList the account’s active device tokens.
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] | |
| currentDeviceId * | string | null | Id of the calling device when authenticated with a device token. |
/v1/auth/devices/{id} Bearer keyRevoke a device token. Use the id current to revoke the device making this call (sign out).
| Name | Type | Description |
|---|---|---|
| id * | string · path | Device id, or the literal current. |
204 Device revoked.
/v1/search Bearer keySearch the user’s CortexPlus memory.
| Name | Type | Description |
|---|---|---|
| query * | string | Text to search for in memory. |
| limit | integer | 1–50, default 10 |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| results * | object[] | |
| results[].id * | string | |
| results[].title * | string | |
| results[].url * | string (uri) | |
| results[].text | string |
/v1/recall Bearer keyBuild context from the user’s CortexPlus memory.
| Name | Type | Description |
|---|---|---|
| query * | string | Question to answer from memory. |
| limit | integer | 1–50, default 10 |
| depth | integer | 0–3, default 1 |
| maxChars | integer | 500–20000, default 6000 |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| text * | string | |
| matches * | integer |
/v1/memories/{id} Bearer keyRetrieve one CortexPlus memory by id. With view=node the full node is returned, as the app routes return it.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
| view | "node" · query |
200 Successful response.
/v1/memories/{id} Bearer keyUpdate a memory and return the full node.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
| Name | Type | Description |
|---|---|---|
| title | string | |
| content | string | |
| type | string | |
| tags | string[] | |
| attributes | object | |
| parentId | string | null | Parent memory id; null detaches the memory. Cycles are rejected. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| ancestors | object[] | |
| ancestors[].id * | string | |
| ancestors[].title * | string | |
| ancestors[].type * | string | |
| ancestors[].tags * | string[] | |
| interaction | object | |
| interaction.lastAt * | string | null (date-time) | |
| interaction.days * | integer | null | |
| interaction.answered * | boolean | |
| parent | object | |
| parent.id * | string | |
| parent.title * | string | |
| parent.type * | string | |
| parent.tags * | string[] | |
| relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| relevance.score | integer | 0–100 |
| relevance.level | "low" | "normal" | "high" | "critical" | |
| relevance.reasons | string[] | |
| relevance.snoozedUntil | string | null (date) | |
| relevance.aiDelta | integer | -20–20 |
/v1/memories/{id} Bearer keyDelete one CortexPlus memory by id.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
204 Memory deleted.
/v1/memories/{id}/ancestors Bearer keyReturn the chain of parent memories, from the root down to the direct parent.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] | |
| items[].ancestors | object[] | |
| items[].interaction | object | |
| items[].parent | object | |
| items[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| limit | integer | |
| offset | integer | |
| removed | string[] | |
| nextCursor | string | null | |
| syncToken | string | null | |
| reset | boolean |
/v1/memories/{id}/descendants Bearer keyReturn every memory nested under this one, breadth-first. Each item has depth (1 = direct child).
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
| maxDepth | integer · query | ≥ 1 |
| limit | integer · query | 1–2000, default 500 |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] | |
| items[].ancestors | object[] | |
| items[].interaction | object | |
| items[].parent | object | |
| items[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| truncated * | boolean |
/v1/memories/{id}/horizon Bearer keySet how the memory is highlighted or expires. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
| Name | Type | Description |
|---|---|---|
| kind * | "persistent" | "recurring" | "dated" | "short" | persistent: highlighted every day; recurring: highlighted every interval; dated: highlighted from date on; short: archived after days. |
| interval | "daily" | "weekly" | "biweekly" | Required when kind is recurring. |
| date | string (date) | Required when kind is dated (YYYY-MM-DD). |
| days | integer | Short-term lifetime; defaults to 7. · 1–365 |
| notify | boolean | Send an own reminder (not for short). Without time it fires at 09:00 in the user timezone. |
| time | string | Reminder time (HH:MM) in the user timezone. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| ancestors | object[] | |
| ancestors[].id * | string | |
| ancestors[].title * | string | |
| ancestors[].type * | string | |
| ancestors[].tags * | string[] | |
| interaction | object | |
| interaction.lastAt * | string | null (date-time) | |
| interaction.days * | integer | null | |
| interaction.answered * | boolean | |
| parent | object | |
| parent.id * | string | |
| parent.title * | string | |
| parent.type * | string | |
| parent.tags * | string[] | |
| relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| relevance.score | integer | 0–100 |
| relevance.level | "low" | "normal" | "high" | "critical" | |
| relevance.reasons | string[] | |
| relevance.snoozedUntil | string | null (date) | |
| relevance.aiDelta | integer | -20–20 |
/v1/memories/{id}/horizon Bearer keyStop highlighting the memory. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| ancestors | object[] | |
| ancestors[].id * | string | |
| ancestors[].title * | string | |
| ancestors[].type * | string | |
| ancestors[].tags * | string[] | |
| interaction | object | |
| interaction.lastAt * | string | null (date-time) | |
| interaction.days * | integer | null | |
| interaction.answered * | boolean | |
| parent | object | |
| parent.id * | string | |
| parent.title * | string | |
| parent.type * | string | |
| parent.tags * | string[] | |
| relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| relevance.score | integer | 0–100 |
| relevance.level | "low" | "normal" | "high" | "critical" | |
| relevance.reasons | string[] | |
| relevance.snoozedUntil | string | null (date) | |
| relevance.aiDelta | integer | -20–20 |
/v1/memories/{id}/ack Bearer keyHide the memory from highlights until its next occurrence. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| ancestors | object[] | |
| ancestors[].id * | string | |
| ancestors[].title * | string | |
| ancestors[].type * | string | |
| ancestors[].tags * | string[] | |
| interaction | object | |
| interaction.lastAt * | string | null (date-time) | |
| interaction.days * | integer | null | |
| interaction.answered * | boolean | |
| parent | object | |
| parent.id * | string | |
| parent.title * | string | |
| parent.type * | string | |
| parent.tags * | string[] | |
| relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| relevance.score | integer | 0–100 |
| relevance.level | "low" | "normal" | "high" | "critical" | |
| relevance.reasons | string[] | |
| relevance.snoozedUntil | string | null (date) | |
| relevance.aiDelta | integer | -20–20 |
/v1/memories/{id}/complete Bearer keyMark the memory as done and archive it. With `cascade: true`, every open subtask (descendant of type task) is completed too. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
| Name | Type | Description |
|---|---|---|
| cascade | boolean |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| ancestors | object[] | |
| ancestors[].id * | string | |
| ancestors[].title * | string | |
| ancestors[].type * | string | |
| ancestors[].tags * | string[] | |
| interaction | object | |
| interaction.lastAt * | string | null (date-time) | |
| interaction.days * | integer | null | |
| interaction.answered * | boolean | |
| parent | object | |
| parent.id * | string | |
| parent.title * | string | |
| parent.type * | string | |
| parent.tags * | string[] | |
| relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| relevance.score | integer | 0–100 |
| relevance.level | "low" | "normal" | "high" | "critical" | |
| relevance.reasons | string[] | |
| relevance.snoozedUntil | string | null (date) | |
| relevance.aiDelta | integer | -20–20 |
/v1/memories/{id}/reopen Bearer keyUndo completion and bring the memory back from the archive. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| ancestors | object[] | |
| ancestors[].id * | string | |
| ancestors[].title * | string | |
| ancestors[].type * | string | |
| ancestors[].tags * | string[] | |
| interaction | object | |
| interaction.lastAt * | string | null (date-time) | |
| interaction.days * | integer | null | |
| interaction.answered * | boolean | |
| parent | object | |
| parent.id * | string | |
| parent.title * | string | |
| parent.type * | string | |
| parent.tags * | string[] | |
| relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| relevance.score | integer | 0–100 |
| relevance.level | "low" | "normal" | "high" | "critical" | |
| relevance.reasons | string[] | |
| relevance.snoozedUntil | string | null (date) | |
| relevance.aiDelta | integer | -20–20 |
/v1/memories/{id}/archive Bearer keyHide the memory from default listings and highlights. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| ancestors | object[] | |
| ancestors[].id * | string | |
| ancestors[].title * | string | |
| ancestors[].type * | string | |
| ancestors[].tags * | string[] | |
| interaction | object | |
| interaction.lastAt * | string | null (date-time) | |
| interaction.days * | integer | null | |
| interaction.answered * | boolean | |
| parent | object | |
| parent.id * | string | |
| parent.title * | string | |
| parent.type * | string | |
| parent.tags * | string[] | |
| relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| relevance.score | integer | 0–100 |
| relevance.level | "low" | "normal" | "high" | "critical" | |
| relevance.reasons | string[] | |
| relevance.snoozedUntil | string | null (date) | |
| relevance.aiDelta | integer | -20–20 |
/v1/memories/{id}/unarchive Bearer keyBring an archived memory back to default listings. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| ancestors | object[] | |
| ancestors[].id * | string | |
| ancestors[].title * | string | |
| ancestors[].type * | string | |
| ancestors[].tags * | string[] | |
| interaction | object | |
| interaction.lastAt * | string | null (date-time) | |
| interaction.days * | integer | null | |
| interaction.answered * | boolean | |
| parent | object | |
| parent.id * | string | |
| parent.title * | string | |
| parent.type * | string | |
| parent.tags * | string[] | |
| relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| relevance.score | integer | 0–100 |
| relevance.level | "low" | "normal" | "high" | "critical" | |
| relevance.reasons | string[] | |
| relevance.snoozedUntil | string | null (date) | |
| relevance.aiDelta | integer | -20–20 |
/v1/memories/{id}/comments Bearer keyReturn the dated comments of a memory, newest first.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
| limit | integer · query | 1–200, default 200 |
| before | string (date-time) · query | Only comments created before this ISO time (pagination cursor). |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] | |
| items[].id * | string | |
| items[].nodeId * | string | |
| items[].body * | string | |
| items[].createdAt * | string (date-time) | |
| items[].updatedAt | string (date-time) |
/v1/memories/{id}/comments Bearer keyAdd a dated comment; it also marks the highlight as handled today. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
| Name | Type | Description |
|---|---|---|
| body * | string | 1–5000 chars |
201 Successful response.
| Name | Type | Description |
|---|---|---|
| id * | string | |
| nodeId * | string | |
| body * | string | |
| createdAt * | string (date-time) | |
| updatedAt | string (date-time) |
/v1/memories/{id}/attachment Bearer keyReturn a short-lived download URL for the memory attachment. The URL expires after expiresIn seconds. Returns 404 when the memory has no stored attachment.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
| variant | "thumb" | "original" · query | Return a thumbnail URL when available, otherwise the original attachment URL. · default "original" |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| url * | string (uri) | |
| expiresIn * | number |
/v1/memories/{id}/photo Bearer keyRemove the attachment from the memory and delete its stored photo. Meals and notes are preserved. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
200 Successful response.
/v1/memories/{id}/nutrition/retry Bearer keyRe-run the nutrition estimate for a meal memory with an optional replacement description, and return the updated node. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
| Name | Type | Description |
|---|---|---|
| description | string | 0–2000 chars |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| node * | object | Full node as returned by the CortexPlus backend. |
| node.ancestors | object[] | |
| node.interaction | object | |
| node.parent | object | |
| node.relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
/v1/memories/{id}/repeat Bearer keyCopy a ready meal to today without its attachment. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
| Name | Type | Description |
|---|---|---|
| clientId | string | 0–200 chars |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| node * | object | Full node as returned by the CortexPlus backend. |
| node.ancestors | object[] | |
| node.interaction | object | |
| node.parent | object | |
| node.relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| duplicate * | boolean |
/v1/memories/{id}/nutrition/adjust Bearer keyRecalculate a meal memory using a nutrition-label photo or a named product, and return the updated node. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Memory id. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| node * | object | Full node as returned by the CortexPlus backend. |
| node.ancestors | object[] | |
| node.interaction | object | |
| node.parent | object | |
| node.relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
/v1/remember Bearer keyStore a note in the user’s CortexPlus memory.
| Name | Type | Description |
|---|---|---|
| content * | string | Note content to store. |
| title | string | |
| tags | string[] | |
| type | string | default "note" |
| attributes | object | Additional node attributes. |
| parentId | string | Id of an existing memory to nest this note under. |
201 Successful response.
| Name | Type | Description |
|---|---|---|
| id * | string | |
| title | string |
/v1/uploads Bearer keyCreate a signed upload URL for an audio, photo, or video memory.
| Name | Type | Description |
|---|---|---|
| name * | string | Name of the audio file. |
| contentType * | string | MIME type of the audio file. |
| size | integer | Exact file size in bytes. When sent, oversized files are rejected before signing and the PUT must send this exact Content-Length. · ≥ 1 |
| expiresIn | integer | Presigned URL lifetime in seconds. · 60–86400 |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| key * | string | |
| uploadUrl * | string (uri) | |
| expiresIn * | integer |
/v1/memories Bearer keyList the account’s memories ordered by last update, or search them semantically with q. Supply changedSince to fetch memory changes since a sync token. Returns full nodes.
| Name | Type | Description |
|---|---|---|
| limit | integer · query | 1–100, default 30 |
| offset | integer · query | Nonzero offsets cannot be combined with changedSince. · ≥ 0, default 0 |
| changedSince | string · query | Sync token from an earlier memories list or delta response; cannot be combined with q. · 1–∞ chars |
| cursor | string · query | Delta pagination cursor; only valid with changedSince. · 1–∞ chars |
| type | string · query | |
| tag | string[] · query | Repeatable tag filter. |
| client | string · query | |
| excludePhotos | boolean · query | Hide image and video notes from generic memory lists. |
| q | string · query | Semantic search query. |
| mode | "semantic" | "text" · query | default "semantic" |
| parentId | string · query | Only direct children of this memory id; `root` returns only memories without a parent. |
| archived | "false" | "true" | "all" · query | Archived memories (completed tasks, expired short-term memories) are hidden by default; `true` lists only them and `all` lists both. Ignored when q is set. · default "false" |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] | |
| items[].ancestors | object[] | |
| items[].interaction | object | |
| items[].parent | object | |
| items[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| limit | integer | |
| offset | integer | |
| removed | string[] | |
| nextCursor | string | null | |
| syncToken | string | null | |
| reset | boolean |
/v1/memories Bearer keyClassify and save text from a note, task, or reminder, or ingest photos and videos by storage key. Binary audio is sent to storage and transcribed asynchronously; binary images are described and OCRed asynchronously.
| Name | Type | Description |
|---|---|---|
| Idempotency-Key | string · header | Client-generated idempotency key; overrides clientId in the request body or query. · 8–100 chars |
| clientId | string · query | Client id fallback for JSON or binary captures; body clientId takes precedence for JSON, and Idempotency-Key takes precedence over both. · 8–100 chars |
| capturedAt | string (date-time) · query | ISO capture time fallback for JSON or binary captures; body capturedAt takes precedence for JSON. |
| capturedAtSource | "clock" | "exif" | "takeout" | "file" | "user" · query | Capture date source for JSON or binary captures; body capturedAtSource takes precedence for JSON. |
| auto | "0" | "1" | "true" | "false" · query | Binary uploads: set to 1 to classify by content (meal, task, reminder, note) instead of mode. |
| lat | number · query | Capture latitude for binary uploads; requires lon. · -90–90 |
| lon | number · query | Capture longitude for binary uploads; requires lat. · -180–180 |
| accuracy | number · query | Optional capture accuracy in meters for binary uploads. · ≥ 0 |
Option 1
| Name | Type | Description |
|---|---|---|
| text * | string | Text to classify and save. |
| tags | string[] | |
| via | string | |
| location | object | Capture coordinates recorded in attributes.location. The backend discards the value when the account geolocation setting is off. |
| location.lat * | number | -90–90 |
| location.lon * | number | -180–180 |
| location.accuracy | number | ≥ 0 |
| location.capturedAt | string (date-time) | |
| clientId | string | 8–100 chars |
| capturedAt | string (date-time) | |
| capturedAtSource | "clock" | "exif" | "takeout" | "file" | "user" | |
| auto | boolean | Classify by content instead of mode: detects meals, tasks, reminders and notes and may create several linked memories. |
Option 2
| Name | Type | Description |
|---|---|---|
| key * | string | R2 object key from createUpload. |
| sha256 | string | Optional lowercase hex SHA-256 of the uploaded file; lets CortexPlus deduplicate repeated photos/videos per user. |
| durationSeconds | number | ≥ 0 |
| contentType | string | audio/*, image/* or video/* MIME type; video is ingested only by key, never as a binary body. |
| note | string | Optional text explaining what a photo contains (used by the meal estimate). · 0–2000 chars |
| noteAudioKey | string | Optional R2 key of an audio (from createUpload) explaining the photo; it is transcribed and used with note. |
| noteAudioSeconds | number | Duration of the noteAudioKey audio. · ≥ 0 |
| name | string | |
| tags | string[] | |
| via | string | |
| location | object | Capture coordinates recorded in attributes.location. The backend discards the value when the account geolocation setting is off. |
| location.lat * | number | -90–90 |
| location.lon * | number | -180–180 |
| location.accuracy | number | ≥ 0 |
| location.capturedAt | string (date-time) | |
| clientId | string | 8–100 chars |
| capturedAt | string (date-time) | |
| capturedAtSource | "clock" | "exif" | "takeout" | "file" | "user" | |
| auto | boolean | Classify by content instead of mode: detects meals, tasks, reminders and notes and may create several linked memories. |
Option 3
| Name | Type | Description |
|---|---|---|
| audioBase64 * | string | Base64-encoded audio file, up to 25 MB after decoding. |
| contentType | string | Audio MIME type. |
| name | string | |
| durationSeconds | number | ≥ 0 |
| tags | string[] | |
| via | string | |
| location | object | Capture coordinates recorded in attributes.location. The backend discards the value when the account geolocation setting is off. |
| location.lat * | number | -90–90 |
| location.lon * | number | -180–180 |
| location.accuracy | number | ≥ 0 |
| location.capturedAt | string (date-time) | |
| clientId | string | 8–100 chars |
| capturedAt | string (date-time) | |
| capturedAtSource | "clock" | "exif" | "takeout" | "file" | "user" | |
| auto | boolean | Classify by content instead of mode: detects meals, tasks, reminders and notes and may create several linked memories. |
201 Successful response.
| Name | Type | Description |
|---|---|---|
| id * | string | |
| clientId * | string | null | |
| duplicate * | boolean | |
| type * | string | |
| title * | string | |
| client * | string | null | |
| status * | string | null | |
| memory * | string | null | |
| review * | string | null | |
| resolved * | boolean | null | |
| url * | string (uri) |
/v1/tasks Bearer keyList open tasks and reminders from CortexPlus.
| Name | Type | Description |
|---|---|---|
| status | string · query | Task status to filter by. · default "open" |
| client | string · query | Client name or slug to filter by. |
| limit | integer · query | Maximum number of tasks to return. · 1–50, default 20 |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| tasks * | object[] | |
| tasks[].id * | string | |
| tasks[].title * | string | |
| tasks[].client * | string | null | |
| tasks[].status * | string | null | |
| tasks[].dueAt * | string | null | |
| tasks[].url * | string (uri) |
/v1/apikeys Bearer keyList the account’s API keys.
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] |
/v1/apikeys Bearer keyCreate an API key. The plaintext key is returned only in this response.
| Name | Type | Description |
|---|---|---|
| label * | string |
201 Successful response.
/v1/apikeys/{id} Bearer keyRevoke one API key by id.
| Name | Type | Description |
|---|---|---|
| id * | string · path | API key id. |
204 API key revoked.
/v1/usage Bearer keyReturn the account’s usage counters and plan quotas.
200 Successful response.
/v1/highlights Bearer keyReturn the memories that should be highlighted today in the user timezone (persistent, due recurring and dated memories not yet handled today), with highlight occurrence, a comment summary and a subtask summary (`subtasks: { total, done }`).
| Name | Type | Description |
|---|---|---|
| limit | integer · query | 1–200 |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| day * | string (date) | |
| timezone * | string | |
| items * | object[] | |
| items[].ancestors | object[] | |
| items[].interaction | object | |
| items[].parent | object | |
| items[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
/v1/notifications Bearer keyReturn the notification inbox, newest first. Page with before=nextCursor.
| Name | Type | Description |
|---|---|---|
| limit | integer · query | 1–100 |
| before | string (date-time) · query | |
| unread | "true" | "false" · query |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] | |
| items[].id * | string | |
| items[].type * | string | e.g. memory.highlights.daily, memory.task.due, finance.bill.due. |
| items[].category * | "memory" | "finance" | "capture" | "account" | |
| items[].title * | string | |
| items[].body * | string | |
| items[].data * | object | Deep-link hints: screen (memory, highlights, finance, usage) and id. |
| items[].nodeId * | string | null | |
| items[].createdAt * | string (date-time) | |
| items[].readAt * | string | null (date-time) | |
| nextCursor * | string | null | |
| unread * | integer |
/v1/notifications/unread Bearer key200 Successful response.
| Name | Type | Description |
|---|---|---|
| unread * | integer |
/v1/notifications/read Bearer keyMark notifications as read. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| ids * | string[] |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| ids * | string[] | |
| unread * | integer |
/v1/notifications/read-all Bearer keyMark every notification as read. Requires the cortex.write scope.
200 Successful response.
| Name | Type | Description |
|---|---|---|
| ids * | string[] | |
| unread * | integer |
/v1/notifications/archive Bearer keyRemove notifications from the inbox. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| ids * | string[] |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| ids * | string[] | |
| unread * | integer |
/v1/notifications/preferences Bearer key200 Successful response.
| Name | Type | Description |
|---|---|---|
| categories | object | Per category ({memory, finance, capture, account}) channel switches. |
| digest | object | |
| digest.enabled | boolean | |
| digest.time | string | |
| quietHours | object | |
| quietHours.enabled | boolean | |
| quietHours.start | string | |
| quietHours.end | string | |
| preview | "title" | "full" | title keeps the memory content off the lock screen. |
/v1/notifications/preferences Bearer keyPartial merge of the preferences. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| categories | object | Per category ({memory, finance, capture, account}) channel switches. |
| digest | object | |
| digest.enabled | boolean | |
| digest.time | string | |
| quietHours | object | |
| quietHours.enabled | boolean | |
| quietHours.start | string | |
| quietHours.end | string | |
| preview | "title" | "full" | title keeps the memory content off the lock screen. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| categories | object | Per category ({memory, finance, capture, account}) channel switches. |
| digest | object | |
| digest.enabled | boolean | |
| digest.time | string | |
| quietHours | object | |
| quietHours.enabled | boolean | |
| quietHours.start | string | |
| quietHours.end | string | |
| preview | "title" | "full" | title keeps the memory content off the lock screen. |
/v1/notifications/push Bearer key200 Successful response.
| Name | Type | Description |
|---|---|---|
| fcm * | boolean | |
| webpush * | boolean | |
| vapidPublicKey * | string | null |
/v1/notifications/push Bearer keyfcm needs pushToken (the Firebase registration token); webpush needs the browser subscription. With a device token the target is removed when the device is revoked. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| provider * | "fcm" | "webpush" | |
| pushToken | string | 0–4096 chars |
| subscription | object | |
| platform | string | e.g. android, ios, web. |
200 Successful response.
/v1/notifications/push Bearer keyRequires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| pushToken | string | |
| endpoint | string |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| removed * | boolean |
/v1/notifications/test Bearer keyCreate a test notification in the inbox and push it. Requires the cortex.write scope.
200 Successful response.
/v1/consolidation Bearer keyReturn the consolidation brief and conversation turns. Requires the Subscription plan.
| Name | Type | Description |
|---|---|---|
| day | string (date) · query |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| day * | string (date) | |
| status * | "ready" | "running" | "failed" | "none" | |
| brief * | object | null | Daily brief with generatedAt, summary, sections and questions. |
| brief.day | string (date) | |
| brief.generatedAt | string (date-time) | |
| brief.summary | string | |
| brief.sections | object[] | |
| brief.questions | object[] | |
| turns * | object[] | |
| turns[].id * | string | |
| turns[].day * | string (date) | |
| turns[].createdAt * | string (date-time) | |
| turns[].transcript * | string | |
| turns[].reply * | string | |
| turns[].warning | string | |
| turns[].actions * | object[] |
402 The account needs the Subscription plan.
| Name | Type | Description |
|---|---|---|
| error * | "subscription_required" |
/v1/consolidation/run Bearer keyThe operation is idempotent per day; force regenerates the consolidation. Requires the Subscription plan. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| force | boolean |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| day * | string (date) | |
| status * | "ready" | "running" | "failed" | "none" | |
| brief * | object | null | Daily brief with generatedAt, summary, sections and questions. |
| brief.day | string (date) | |
| brief.generatedAt | string (date-time) | |
| brief.summary | string | |
| brief.sections | object[] | |
| brief.questions | object[] | |
| turns * | object[] | |
| turns[].id * | string | |
| turns[].day * | string (date) | |
| turns[].createdAt * | string (date-time) | |
| turns[].transcript * | string | |
| turns[].reply * | string | |
| turns[].warning | string | |
| turns[].actions * | object[] |
402 The account needs the Subscription plan.
| Name | Type | Description |
|---|---|---|
| error * | "subscription_required" |
/v1/consolidation/preferences Bearer keyReturn the daily consolidation schedule. Requires the Subscription plan.
200 Successful response.
| Name | Type | Description |
|---|---|---|
| enabled * | boolean | |
| time * | string | |
| digestTime * | string |
402 The account needs the Subscription plan.
| Name | Type | Description |
|---|---|---|
| error * | "subscription_required" |
/v1/consolidation/preferences Bearer keyMerge the supplied schedule preferences. Requires the Subscription plan. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| enabled | boolean | |
| time | string | |
| digestTime | string |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| enabled * | boolean | |
| time * | string | |
| digestTime * | string |
402 The account needs the Subscription plan.
| Name | Type | Description |
|---|---|---|
| error * | "subscription_required" |
/v1/consolidation/chat Bearer keySend text or audio to discuss the daily brief. Requires the Subscription plan. Requires the cortex.write scope.
200 Successful response.
| Name | Type | Description |
|---|---|---|
| id * | string | |
| day * | string (date) | |
| createdAt * | string (date-time) | |
| transcript * | string | |
| reply * | string | |
| warning | string | |
| actions * | object[] | |
| actions[].id * | string | |
| actions[].type * | string | |
| actions[].status * | "applied" | "failed" | "undone" | |
| actions[].summary * | string | |
| actions[].nodeId * | string | null | |
| actions[].undoable * | boolean |
402 The account needs the Subscription plan.
| Name | Type | Description |
|---|---|---|
| error * | "subscription_required" |
/v1/consolidation/undo Bearer keyUndo a reversible action from a conversation turn. Requires the Subscription plan. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| actionId * | string |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| action * | object | |
| action.id * | string | |
| action.type * | string | |
| action.status * | "applied" | "failed" | "undone" | |
| action.summary * | string | |
| action.nodeId * | string | null | |
| action.undoable * | boolean |
402 The account needs the Subscription plan.
| Name | Type | Description |
|---|---|---|
| error * | "subscription_required" |
/v1/comments/{id} Bearer keyReplace the comment body. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Comment id. |
| Name | Type | Description |
|---|---|---|
| body * | string | 1–5000 chars |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| id * | string | |
| nodeId * | string | |
| body * | string | |
| createdAt * | string (date-time) | |
| updatedAt | string (date-time) |
/v1/comments/{id} Bearer keyRemove the comment. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| id * | string · path | Comment id. |
204 Comment deleted.
/v1/uploads/known Bearer keyReturn which hashes the user already stored, with their nodeId, so the client can skip re-uploading. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| hashes * | string[] |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| known * | object[] | |
| known[].sha256 * | string | |
| known[].nodeId * | string |
/v1/photos Bearer keyList image and video memories ordered by capture time using cursor pagination. Supply changedSince to fetch photo-grid changes since a sync token.
| Name | Type | Description |
|---|---|---|
| limit | integer · query | 1–100, default 60 |
| cursor | string · query | 1–∞ chars |
| changedSince | string · query | Sync token from an earlier photo-list or delta response. · 1–∞ chars |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] | |
| items[].ancestors | object[] | |
| items[].interaction | object | |
| items[].parent | object | |
| items[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| nextCursor * | string | null | |
| syncToken * | string | null | Token to use for the next photo-grid delta sync. |
| removed | string[] | Photo node IDs to remove from the local grid in delta mode. |
| reset | boolean | True when the supplied sync token is too old and the client must reload the full grid. |
/v1/blobs/fetch/{requestId} Bearer keyReturn the status of a request to restore an evicted original attachment from a machine runner.
| Name | Type | Description |
|---|---|---|
| requestId * | string (uuid) · path | Blob fetch request UUID. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| status * | "ready" | "pending" | "expired" | "error" | |
| url | string (uri) | |
| expiresIn | number |
/v1/blobs/replicated Bearer keyReturns hashes that have a replica on a non-revoked machine runner.
| Name | Type | Description |
|---|---|---|
| sha256s * | string[] |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| replicated * | object[] | |
| replicated[].sha256 * | string | |
| replicated[].size * | integer |
/v1/context-packs Bearer keyList saved AI session handoff summaries (context packs), optionally filtered by platform.
| Name | Type | Description |
|---|---|---|
| platform | string · query | Platform filter, e.g. chatgpt or claude. |
| limit | integer · query | Maximum number of packs to return. · 1–50, default 20 |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| packs * | object[] | |
| packs[].id * | string | |
| packs[].title * | string | |
| packs[].platform * | string | null | |
| packs[].url * | string (uri) | |
| packs[].savedAt * | string | null |
/v1/context-packs Bearer keySave an AI session handoff summary to CortexPlus memory. Secrets in the content are replaced by placeholders before storing; the secret values are never persisted. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| content * | string | Handoff summary in Markdown. |
| platform * | string | AI platform that wrote the summary, e.g. chatgpt or claude. |
| key * | string | Short stable slug for the topic. Sending the same platform and key again updates the pack instead of creating another. |
| title | string | |
| model | string | |
| messageCount | integer | 0–100000 |
| tags | string[] |
201 Successful response.
| Name | Type | Description |
|---|---|---|
| id * | string | |
| title * | string | |
| url * | string (uri) | |
| created * | boolean | |
| redactions * | object[] | |
| redactions[].kind * | string | |
| redactions[].placeholder * | string | |
| redactions[].count * | integer |
/v1/context-packs/resume Bearer keyLoad a saved context pack by id or by semantic query to resume work started in another AI conversation.
| Name | Type | Description |
|---|---|---|
| query | string | Topic to find the pack by, in natural language. |
| id | string | Pack id, as returned by listContextPacks. |
| maxChars | integer | 500–20000, default 6000 |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| text * | string | |
| pack * | object | null | |
| pack.id | string | |
| pack.title | string | |
| pack.url | string (uri) | |
| matches * | integer |
/v1/study/due Bearer keyList study flashcards due for review, oldest first.
| Name | Type | Description |
|---|---|---|
| subject | string · query | Subject name or slug (`materia:<slug>` tag) to filter by. |
| limit | integer · query | Maximum number of flashcards to return. · 1–100, default 20 |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] | |
| items[].ancestors | object[] | |
| items[].interaction | object | |
| items[].parent | object | |
| items[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
/v1/study/review Bearer keyApply an SM-2 grade to a flashcard and return it with the new schedule. Returns 404 when the card does not exist. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| cardId * | string | Flashcard memory id. |
| grade * | "again" | "hard" | "good" | "easy" |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| card * | object | Full node as returned by the CortexPlus backend. |
| card.ancestors | object[] | |
| card.interaction | object | |
| card.parent | object | |
| card.relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
/v1/study/quiz Bearer keyGenerate a multiple-choice quiz from the study material of a subject. Nothing is stored.
| Name | Type | Description |
|---|---|---|
| subject * | string | Subject name or slug. |
| count | integer | 1–10, default 5 |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] | |
| items[].question * | string | |
| items[].options * | string[] | |
| items[].answerIndex * | integer | |
| items[].explanation * | string | |
| items[].sourceId * | string | null |
/v1/modes Bearer keyList the memory modes with per-user enabled flags and the selected mode.
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] | |
| selected * | string |
/v1/modes/choose Bearer keyEnable exactly the given modes, disable the others except `all`, and mark the first-run mode choice as done. Requires the cortex.write scope.
| Name | Type | Description |
|---|---|---|
| keys * | string[] |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| items * | object[] | |
| selected * | string |
/v1/sales/brief Bearer keySummarize a client’s sales memories with the open deal, last contact, and next follow-up.
| Name | Type | Description |
|---|---|---|
| client * | string | Client name or slug. |
| includeClosed | boolean | Include closed opportunities. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| summary * | string | |
| openDeal * | ||
| lastContactAt * | string | null | |
| nextFollowup * | ||
| sources * | string[] | |
| clientNode * | ||
| comments * | object[] | |
| comments[].id * | string | |
| comments[].nodeId * | string | |
| comments[].body * | string | |
| comments[].createdAt * | string (date-time) | |
| comments[].updatedAt * | string (date-time) | |
| tasks * | object[] | |
| tasks[].ancestors | object[] | |
| tasks[].interaction | object | |
| tasks[].parent | object | |
| tasks[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| contacts * | object[] | |
| contacts[].ancestors | object[] | |
| contacts[].interaction | object | |
| contacts[].parent | object | |
| contacts[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| opportunities * | object[] | |
| opportunities[].ancestors | object[] | |
| opportunities[].interaction | object | |
| opportunities[].parent | object | |
| opportunities[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
/v1/sales/opportunities/{id} Bearer keyReturn an opportunity, its client, contacts, comments, tasks and related sales memories.
| Name | Type | Description |
|---|---|---|
| id * | string · path |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| node * | object | Full node as returned by the CortexPlus backend. |
| node.ancestors | object[] | |
| node.interaction | object | |
| node.parent | object | |
| node.relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| client * | ||
| contacts * | object[] | |
| contacts[].ancestors | object[] | |
| contacts[].interaction | object | |
| contacts[].parent | object | |
| contacts[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| comments * | object[] | |
| comments[].id * | string | |
| comments[].nodeId * | string | |
| comments[].body * | string | |
| comments[].createdAt * | string (date-time) | |
| comments[].updatedAt * | string (date-time) | |
| tasks * | object[] | |
| tasks[].ancestors | object[] | |
| tasks[].interaction | object | |
| tasks[].parent | object | |
| tasks[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| related * | object[] | |
| related[].ancestors | object[] | |
| related[].interaction | object | |
| related[].parent | object | |
| related[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
404 Successful response.
| Name | Type | Description |
|---|---|---|
| error | string |
/v1/finance/month Bearer keyReturn expenses, income, spending by category against budgets, and upcoming bills for a month.
| Name | Type | Description |
|---|---|---|
| month * | string · query | Month to summarize. |
| timezone | string · query | IANA time zone; defaults to the account setting. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| month * | string | |
| currency * | string | |
| expenses * | number | |
| income * | number | |
| byCategory * | object[] | |
| byCategory[].category * | string | |
| byCategory[].spent * | number | |
| byCategory[].budget * | number | null | |
| upcomingBills * | object[] | |
| upcomingBills[].ancestors | object[] | |
| upcomingBills[].interaction | object | |
| upcomingBills[].parent | object | |
| upcomingBills[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
/v1/health/summary Bearer keyHealth data is only returned to API keys/agents when the user enabled `settings.healthAgentAccess`; otherwise the response is `{ "error": "health data is not shared with agents" }`. Summarize latest body metrics, 180-day series, flagged lab results, recent exams, routines and last workout.
| Name | Type | Description |
|---|---|---|
| timezone | string · query | IANA time zone; defaults to the account setting. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| latest * | object | |
| series * | object | |
| flaggedResults * | object[] | |
| flaggedResults[].nodeId * | string | |
| flaggedResults[].date * | string | |
| flaggedResults[].key * | string | |
| flaggedResults[].name * | string | |
| flaggedResults[].value * | number | null | |
| flaggedResults[].unit * | string | null | |
| flaggedResults[].flag * | "low" | "high" | |
| recentExams * | object[] | |
| recentExams[].ancestors | object[] | |
| recentExams[].interaction | object | |
| recentExams[].parent | object | |
| recentExams[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| routines * | object[] | |
| routines[].ancestors | object[] | |
| routines[].interaction | object | |
| routines[].parent | object | |
| routines[].relevance | object | null | Computed relevance (not stored): score 0-100, level, reason codes. null when no scorer applies. |
| lastWorkout * |
/v1/health/metric Bearer keyHealth data is only returned to API keys/agents when the user enabled `settings.healthAgentAccess`; otherwise the response is `{ "error": "health data is not shared with agents" }`. Get a body metric or lab result series.
| Name | Type | Description |
|---|---|---|
| key * | string · query | Body metric key (weightKg, heightCm, bmi, bodyFatPct, muscleMassKg, visceralFat, bodyWaterPct, boneMassKg, basalMetabolismKcal, metabolicAge) or `lab:<resultKey>`, e.g. `lab:glicose`. |
| from | string (date) · query | First date in the metric series. |
| to | string (date) · query | Last date in the metric series. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| key * | string | |
| unit * | string | null | |
| points * | object[] | |
| points[].date * | string | |
| points[].value * | number | |
| points[].nodeId * | string | |
| points[].source * | "measurement" | "exam" |
/v1/nutrition/history Bearer keyNutrient intake from logged meals, aggregated by day, week or month. Weekly and monthly values are daily averages over days with meals. Health-tagged memories hidden from the credential are excluded.
| Name | Type | Description |
|---|---|---|
| from * | string (date) · query | First local date (inclusive). |
| to * | string (date) · query | Last local date (inclusive). Up to 366 days for `day`, 1830 for `week`/`month`. |
| granularity | "day" | "week" | "month" · query | Bucket size; weeks start on Monday. · default "day" |
| timezone | string · query | IANA time zone; defaults to the account setting. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| from * | string (date) | |
| to * | string (date) | |
| granularity * | "day" | "week" | "month" | |
| timezone * | string | |
| nutrients * | object[] | |
| nutrients[].key * | string | |
| nutrients[].unit * | string | |
| buckets * | object[] | |
| buckets[].start * | string (date) | |
| buckets[].end * | string (date) | |
| buckets[].days * | integer | Days with at least one meal. |
| buckets[].meals * | integer | |
| buckets[].average * | object | Daily average over days with meals. |
| buckets[].total * | object | Values keyed by `<nutrient>:<unit>`, e.g. `enerc:kcal`, `procnt:g`, `vitc:mg`. |
| summary * | object | |
| summary.days * | integer | Days with at least one meal. |
| summary.meals * | integer | |
| summary.average * | object | Daily average over days with meals. |
| summary.total * | object | Values keyed by `<nutrient>:<unit>`, e.g. `enerc:kcal`, `procnt:g`, `vitc:mg`. |
/v1/nutrition/targets Bearer keyOnly returned to API keys/agents when the user enabled `settings.healthAgentAccess`; otherwise the response is `{ "error": "health data is not shared with agents" }`. Daily ranges per nutrient from the profile (birth date, sex, activity level), the latest weight/height and the active calorie goal; generic adult references when the profile is incomplete.
| Name | Type | Description |
|---|---|---|
| timezone | string · query | IANA time zone; defaults to the account setting. |
200 Successful response.
| Name | Type | Description |
|---|---|---|
| profile * | object | Inputs used (birthDate, age, sex, activityLevel, weightKg, heightCm, calorieGoalKcal), `missing` fields and `supportedAge`. |
| basis * | "personal" | "generic" | |
| energyKcal * | object | |
| energyKcal.value * | number | |
| energyKcal.source * | "goal" | "eer" | "dv" | |
| energyKcal.eer | number | null | |
| targets * | object[] | |
| targets[].key * | string | |
| targets[].unit * | string | |
| targets[].min * | number | null | |
| targets[].max * | number | null | |
| targets[].target * | number | null | |
| targets[].source * | string |
Failures answer with { "error": "..." } and a matching status: 401 without a key, 403 when the key is not allowed to write, 400 when the request is malformed, 404 for an unknown item, 429 when your plan limit is reached, and 503 when memory is briefly unreachable.
Reaching a limit never blocks reading — only new indexing pauses. You can raise it in Billing or compare plans on the pricing page.