REST API reference

Every endpoint of the CortexPlus REST API, generated from the published OpenAPI specification. Field descriptions come straight from the spec, in English.

Interactive reference (Redoc) openapi.json Back to the guide

Base URL and authentication

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.

Authenticated request

curl -sS https://api.cortexplus.io/v1/auth/me \
  -H 'authorization: Bearer cortex_...'

Account and sign-in

POST /v1/signup No auth

Create a CortexPlus account.

Create an account or begin signing in. CortexPlus sends an authentication key by email; use the connect operation with that key next.

Request body application/json

Name	Type	Description
email *	string (email)	Email address for the CortexPlus account.
name	string
client	string	Name of the AI platform requesting the connection.

Responses

202 Successful response.

Name	Type	Description
sent *	boolean
expiresInMinutes *	integer

POST /v1/connect No auth

Connect a CortexPlus account.

Redeem the authentication key received by email. Save the returned apiKey in the connector configuration.

Request body application/json

Name	Type	Description
key *	string	Authentication key received by email.
client	string	Name of the AI platform requesting the connection.

Responses

200 Successful response.

Name	Type	Description
apiKey *	string
email *	string
name *	string

POST /v1/auth/register No auth

Register an account and start a device session.

Create a CortexPlus account and issue a device token for this app install.

Request body application/json

Name	Type	Description
email *	string (email)
name	string
password *	string	8–∞ chars
deviceName	string
platform	string

Responses

201 Successful response.

Name	Type	Description
deviceToken *	string	Device credential (cxd_…); use it as the bearer token.
user *	object

POST /v1/auth/login No auth

Log in and start a device session.

Request body application/json

Name	Type	Description
email *	string (email)
password *	string
deviceName	string
platform	string

Responses

200 Successful response.

Name	Type	Description
deviceToken *	string	Device credential (cxd_…); use it as the bearer token.
user *	object

POST /v1/auth/key No auth

Request an email authentication key.

Send an authentication key to the account email address.

Request body application/json

Name	Type	Description
email *	string (email)

Responses

202 Successful response.

Name	Type	Description
sent *	boolean
expiresInMinutes *	integer

POST /v1/auth/key/redeem No auth

Redeem an email authentication key.

Redeem the authentication key received by email and issue a device token for this app install.

Request body application/json

Name	Type	Description
key *	string	Authentication key received by email.
deviceName	string
platform	string

Responses

200 Successful response.

Name	Type	Description
deviceToken *	string	Device credential (cxd_…); use it as the bearer token.
user *	object

GET /v1/auth/me Bearer key

Get the current account.

Return the account behind the presented credential.

Responses

200 Successful response.

PATCH /v1/auth/me Bearer key

Update the current account profile.

Update the account display name and/or language, timezone and geolocation settings.

Request body application/json

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

Responses

200 Successful response.

POST /v1/auth/password Bearer key

Set or change the account password.

Set a password on a passwordless account, or change it when currentPassword is provided. Other device tokens are revoked.

Request body application/json

Name	Type	Description
newPassword *	string	8–∞ chars
currentPassword	string	Required when the account already has a password.

Responses

204 Password updated.

GET /v1/auth/devices Bearer key

List devices.

List the account’s active device tokens.

Responses

200 Successful response.

Name	Type	Description
items *	object[]
currentDeviceId *	string \| null	Id of the calling device when authenticated with a device token.

DELETE /v1/auth/devices/{id} Bearer key

Revoke a device.

Revoke a device token. Use the id current to revoke the device making this call (sign out).

Parameters

Name	Type	Description
id *	string · path	Device id, or the literal current.

Responses

204 Device revoked.

Memories

POST /v1/search Bearer key

Search memory.

Search the user’s CortexPlus memory.

Request body application/json

Name	Type	Description
query *	string	Text to search for in memory.
limit	integer	1–50, default 10

Responses

200 Successful response.

Name	Type	Description
results *	object[]
results[].id *	string
results[].title *	string
results[].url *	string (uri)
results[].text	string

POST /v1/recall Bearer key

Recall context.

Build context from the user’s CortexPlus memory.

Request body application/json

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

Responses

200 Successful response.

Name	Type	Description
text *	string
matches *	integer

GET /v1/memories/{id} Bearer key

Get a memory.

Retrieve one CortexPlus memory by id.

Parameters

Name	Type	Description
id *	string · path	Memory id.

Responses

200 Successful response.

Name	Type	Description
id *	string
title *	string
text *	string
url *	string (uri)
metadata	object
metadata.type	string
metadata.tags	string[]
metadata.createdAt	string
metadata.updatedAt	string
metadata.client	string \| null
metadata.status	string \| null
metadata.memory	object

PATCH /v1/memories/{id} Bearer key

Update a memory.

Update a memory and return the full node.

Parameters

Name	Type	Description
id *	string · path	Memory id.

Request body application/json

Name	Type	Description
title	string
content	string
type	string
tags	string[]
attributes	object

Responses

200 Successful response.

DELETE /v1/memories/{id} Bearer key

Delete a memory.

Delete one CortexPlus memory by id.

Parameters

Name	Type	Description
id *	string · path	Memory id.

Responses

204 Memory deleted.

POST /v1/remember Bearer key

Remember a note.

Store a note in the user’s CortexPlus memory.

Request body application/json

Name	Type	Description
content *	string	Note content to store.
title	string
tags	string[]
type	string	default "note"

Responses

201 Successful response.

Name	Type	Description
id *	string
title	string

POST /v1/uploads Bearer key

Create an audio upload.

Create a signed upload URL for an audio memory.

Request body application/json

Name	Type	Description
name *	string	Name of the audio file.
contentType *	string	MIME type of the audio file.

Responses

200 Successful response.

Name	Type	Description
key *	string
uploadUrl *	string (uri)
expiresIn *	integer

GET /v1/memories Bearer key

List memories.

List the account’s memories ordered by last update, or search them semantically with q. Returns full nodes.

Parameters

Name	Type	Description
limit	integer · query	1–100, default 30
offset	integer · query	≥ 0, default 0
type	string · query
tag	string[] · query	Repeatable tag filter.
client	string · query
q	string · query	Semantic search query.
mode	"semantic" \| "text" · query	default "semantic"

Responses

200 Successful response.

Name	Type	Description
items *	object[]
limit	integer
offset	integer

POST /v1/memories Bearer key

Save a memory.

Classify and save text from a note, task, or reminder. Binary audio is sent to storage and transcribed asynchronously; binary images are described and OCRed asynchronously.

Parameters

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

Request body application/json, audio/, image/

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)

Option 2

Name	Type	Description
key *	string	R2 object key from createUpload.
durationSeconds	number	≥ 0
contentType	string
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)

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)

Responses

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)

GET /v1/tasks Bearer key

List tasks.

List open tasks and reminders from CortexPlus.

Parameters

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

Responses

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)

API keys and usage

GET /v1/apikeys Bearer key

List API keys.

List the account’s API keys.

Responses

200 Successful response.

Name	Type	Description
items *	object[]

POST /v1/apikeys Bearer key

Create an API key.

Create an API key. The plaintext key is returned only in this response.

Request body application/json

Name	Type	Description
label *	string

Responses

201 Successful response.

DELETE /v1/apikeys/{id} Bearer key

Revoke an API key.

Revoke one API key by id.

Parameters

Name	Type	Description
id *	string · path	API key id.

Responses

204 API key revoked.

GET /v1/usage Bearer key

Get usage summary.

Return the account’s usage counters and plan quotas.

Responses

200 Successful response.

When something goes wrong

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.

REST API reference

Base URL and authentication

Account and sign-in

Create a CortexPlus account.

Request body application/json

Responses

Connect a CortexPlus account.

Request body application/json

Responses

Register an account and start a device session.

Request body application/json

Responses

Log in and start a device session.

Request body application/json

Responses

Request an email authentication key.

Request body application/json

Responses

Redeem an email authentication key.

Request body application/json

Responses

Get the current account.

Responses

Update the current account profile.

Request body application/json

Responses

Set or change the account password.

Request body application/json

Responses

List devices.

Responses

Revoke a device.

Parameters

Responses

Memories

Search memory.

Request body application/json

Responses

Recall context.

Request body application/json

Responses

Get a memory.

Parameters

Responses

Update a memory.

Parameters

Request body application/json

Responses

Delete a memory.

Parameters

Responses

Remember a note.

Request body application/json

Responses

Create an audio upload.

Request body application/json

Responses

List memories.

Parameters

Responses

Save a memory.

Parameters

Request body application/json, audio/*, image/*

Responses

List tasks.

Parameters

Responses

API keys and usage

List API keys.

Responses

Create an API key.

Request body application/json

Responses

Revoke an API key.

Parameters

Responses

Get usage summary.

Responses

When something goes wrong

Request body application/json, audio/, image/