{"openapi":"3.1.0","info":{"title":"CortexPlus REST API","version":"1.0.0","description":"Read and write CortexPlus memory over HTTP. Human-readable reference: https://api.cortexplus.io/docs."},"servers":[{"url":"https://api.cortexplus.io"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/v1/signup":{"post":{"operationId":"signup","summary":"Create a CortexPlus account.","description":"Create an account or begin signing in. CortexPlus sends an authentication key by email; use the connect operation with that key next.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email address for the CortexPlus account."},"name":{"type":"string"},"client":{"type":"string","description":"Name of the AI platform requesting the connection."}}}}}},"responses":{"202":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["sent","expiresInMinutes"],"properties":{"sent":{"type":"boolean"},"expiresInMinutes":{"type":"integer"}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/connect":{"post":{"operationId":"connect","summary":"Connect a CortexPlus account.","description":"Redeem the authentication key received by email. Save the returned apiKey in the connector configuration.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string","description":"Authentication key received by email."},"client":{"type":"string","description":"Name of the AI platform requesting the connection."}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["apiKey","email","name"],"properties":{"apiKey":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/auth/register":{"post":{"operationId":"authRegister","summary":"Register an account and start a device session.","description":"Create a CortexPlus account and issue a device token for this app install.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"password":{"type":"string","minLength":8},"deviceName":{"type":"string"},"platform":{"type":"string"}}}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["deviceToken","user"],"properties":{"deviceToken":{"type":"string","description":"Device credential (cxd_…); use it as the bearer token."},"user":{"type":"object","additionalProperties":true}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/auth/login":{"post":{"operationId":"authLogin","summary":"Log in and start a device session.","description":"Log in with email and password and issue a device token for this app install.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"},"deviceName":{"type":"string"},"platform":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["deviceToken","user"],"properties":{"deviceToken":{"type":"string","description":"Device credential (cxd_…); use it as the bearer token."},"user":{"type":"object","additionalProperties":true}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/auth/key":{"post":{"operationId":"authRequestKey","summary":"Request an email authentication key.","description":"Send an authentication key to the account email address.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"202":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["sent","expiresInMinutes"],"properties":{"sent":{"type":"boolean"},"expiresInMinutes":{"type":"integer"}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/auth/key/redeem":{"post":{"operationId":"authRedeemKey","summary":"Redeem an email authentication key.","description":"Redeem the authentication key received by email and issue a device token for this app install.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string","description":"Authentication key received by email."},"deviceName":{"type":"string"},"platform":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["deviceToken","user"],"properties":{"deviceToken":{"type":"string","description":"Device credential (cxd_…); use it as the bearer token."},"user":{"type":"object","additionalProperties":true}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/auth/me":{"get":{"operationId":"authMe","summary":"Get the current account.","description":"Return the account behind the presented credential.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}},"patch":{"operationId":"authUpdateProfile","summary":"Update the current account profile.","description":"Update the account display name and/or language, timezone and geolocation settings.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"settings":{"type":"object","additionalProperties":false,"properties":{"language":{"type":"string","enum":["pt-BR","en","es"]},"timezone":{"type":"string","minLength":1},"geolocation":{"type":"boolean","default":true,"description":"Record location sent with memory captures."}}}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/auth/password":{"post":{"operationId":"authSetPassword","summary":"Set or change the account password.","description":"Set a password on a passwordless account, or change it when currentPassword is provided. Other device tokens are revoked.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["newPassword"],"properties":{"newPassword":{"type":"string","minLength":8},"currentPassword":{"type":"string","description":"Required when the account already has a password."}}}}}},"responses":{"204":{"description":"Password updated."},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/auth/devices":{"get":{"operationId":"authListDevices","summary":"List devices.","description":"List the account’s active device tokens.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["items","currentDeviceId"],"properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"currentDeviceId":{"type":["string","null"],"description":"Id of the calling device when authenticated with a device token."}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/auth/devices/{id}":{"delete":{"operationId":"authRevokeDevice","summary":"Revoke a device.","description":"Revoke a device token. Use the id current to revoke the device making this call (sign out).","parameters":[{"name":"id","in":"path","required":true,"description":"Device id, or the literal current.","schema":{"type":"string"}}],"responses":{"204":{"description":"Device revoked."},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/search":{"post":{"operationId":"searchMemory","summary":"Search memory.","description":"Search the user’s CortexPlus memory.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","description":"Text to search for in memory."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"type":"object","required":["id","title","url"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"text":{"type":"string"}}}}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/recall":{"post":{"operationId":"recallMemory","summary":"Recall context.","description":"Build context from the user’s CortexPlus memory.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","description":"Question to answer from memory."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10},"depth":{"type":"integer","minimum":0,"maximum":3,"default":1},"maxChars":{"type":"integer","minimum":500,"maximum":20000,"default":6000}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["text","matches"],"properties":{"text":{"type":"string"},"matches":{"type":"integer"}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/memories/{id}":{"get":{"operationId":"getMemory","summary":"Get a memory.","description":"Retrieve one CortexPlus memory by id.","x-openai-isConsequential":false,"parameters":[{"name":"id","in":"path","required":true,"description":"Memory id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["id","title","text","url"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"text":{"type":"string"},"url":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":true,"properties":{"type":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"client":{"type":["string","null"]},"status":{"type":["string","null"]},"memory":{"type":"object","properties":{"status":{"type":["string","null"]},"review":{"type":["string","null"]},"error":{"type":["string","null"]},"audioSeconds":{"type":["number","null"]}}}}}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}},"patch":{"operationId":"updateMemory","summary":"Update a memory.","description":"Update a memory and return the full node.","parameters":[{"name":"id","in":"path","required":true,"description":"Memory id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string"},"content":{"type":"string"},"type":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"attributes":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Full node as returned by the CortexPlus backend."}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}},"delete":{"operationId":"deleteMemory","summary":"Delete a memory.","description":"Delete one CortexPlus memory by id.","parameters":[{"name":"id","in":"path","required":true,"description":"Memory id.","schema":{"type":"string"}}],"responses":{"204":{"description":"Memory deleted."},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/remember":{"post":{"operationId":"rememberNote","summary":"Remember a note.","description":"Store a note in the user’s CortexPlus memory.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["content"],"properties":{"content":{"type":"string","description":"Note content to store."},"title":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"type":{"type":"string","default":"note"}}}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"title":{"type":"string"}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/uploads":{"post":{"operationId":"createUpload","summary":"Create an audio upload.","description":"Create a signed upload URL for an audio memory.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","contentType"],"properties":{"name":{"type":"string","description":"Name of the audio file."},"contentType":{"type":"string","description":"MIME type of the audio file."}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["key","uploadUrl","expiresIn"],"properties":{"key":{"type":"string"},"uploadUrl":{"type":"string","format":"uri"},"expiresIn":{"type":"integer"}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/memories":{"get":{"operationId":"listMemories","summary":"List memories.","description":"List the account’s memories ordered by last update, or search them semantically with q. Returns full nodes.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","description":"Repeatable tag filter.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"client","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Semantic search query."},{"name":"mode","in":"query","schema":{"type":"string","enum":["semantic","text"],"default":"semantic"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Full node as returned by the CortexPlus backend."}},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}},"post":{"operationId":"createMemory","summary":"Save a memory.","description":"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":"Idempotency-Key","in":"header","description":"Client-generated idempotency key; overrides clientId in the request body or query.","schema":{"type":"string","minLength":8,"maxLength":100,"pattern":"^[A-Za-z0-9_-]{8,100}$"}},{"name":"clientId","in":"query","description":"Client id fallback for JSON or binary captures; body clientId takes precedence for JSON, and Idempotency-Key takes precedence over both.","schema":{"type":"string","minLength":8,"maxLength":100,"pattern":"^[A-Za-z0-9_-]{8,100}$"}},{"name":"capturedAt","in":"query","description":"ISO capture time fallback for JSON or binary captures; body capturedAt takes precedence for JSON.","schema":{"type":"string","format":"date-time"}},{"name":"lat","in":"query","description":"Capture latitude for binary uploads; requires lon.","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","in":"query","description":"Capture longitude for binary uploads; requires lat.","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"accuracy","in":"query","description":"Optional capture accuracy in meters for binary uploads.","schema":{"type":"number","minimum":0}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","oneOf":[{"additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","description":"Text to classify and save."},"tags":{"type":"array","items":{"type":"string"}},"via":{"type":"string"},"location":{"type":"object","additionalProperties":false,"required":["lat","lon"],"description":"Capture coordinates recorded in attributes.location. The backend discards the value when the account geolocation setting is off.","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"accuracy":{"type":"number","minimum":0},"capturedAt":{"type":"string","format":"date-time"}}},"clientId":{"type":"string","minLength":8,"maxLength":100,"pattern":"^[A-Za-z0-9_-]{8,100}$"},"capturedAt":{"type":"string","format":"date-time"}}},{"additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string","description":"R2 object key from createUpload."},"durationSeconds":{"type":"number","minimum":0},"contentType":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"via":{"type":"string"},"location":{"type":"object","additionalProperties":false,"required":["lat","lon"],"description":"Capture coordinates recorded in attributes.location. The backend discards the value when the account geolocation setting is off.","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"accuracy":{"type":"number","minimum":0},"capturedAt":{"type":"string","format":"date-time"}}},"clientId":{"type":"string","minLength":8,"maxLength":100,"pattern":"^[A-Za-z0-9_-]{8,100}$"},"capturedAt":{"type":"string","format":"date-time"}}},{"additionalProperties":false,"required":["audioBase64"],"properties":{"audioBase64":{"type":"string","description":"Base64-encoded audio file, up to 25 MB after decoding."},"contentType":{"type":"string","description":"Audio MIME type."},"name":{"type":"string"},"durationSeconds":{"type":"number","minimum":0},"tags":{"type":"array","items":{"type":"string"}},"via":{"type":"string"},"location":{"type":"object","additionalProperties":false,"required":["lat","lon"],"description":"Capture coordinates recorded in attributes.location. The backend discards the value when the account geolocation setting is off.","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"accuracy":{"type":"number","minimum":0},"capturedAt":{"type":"string","format":"date-time"}}},"clientId":{"type":"string","minLength":8,"maxLength":100,"pattern":"^[A-Za-z0-9_-]{8,100}$"},"capturedAt":{"type":"string","format":"date-time"}}}]}},"audio/*":{"schema":{"type":"string","format":"binary"}},"image/*":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["id","clientId","duplicate","type","title","client","status","memory","review","resolved","url"],"properties":{"id":{"type":"string"},"clientId":{"type":["string","null"]},"duplicate":{"type":"boolean"},"type":{"type":"string"},"title":{"type":"string"},"client":{"type":["string","null"]},"status":{"type":["string","null"]},"memory":{"type":["string","null"]},"review":{"type":["string","null"]},"resolved":{"type":["boolean","null"]},"url":{"type":"string","format":"uri"}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/apikeys":{"get":{"operationId":"listApiKeys","summary":"List API keys.","description":"List the account’s API keys.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}},"post":{"operationId":"createApiKey","summary":"Create an API key.","description":"Create an API key. The plaintext key is returned only in this response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["label"],"properties":{"label":{"type":"string"}}}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/apikeys/{id}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke an API key.","description":"Revoke one API key by id.","parameters":[{"name":"id","in":"path","required":true,"description":"API key id.","schema":{"type":"string"}}],"responses":{"204":{"description":"API key revoked."},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/usage":{"get":{"operationId":"getUsage","summary":"Get usage summary.","description":"Return the account’s usage counters and plan quotas.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}},"/v1/tasks":{"get":{"operationId":"listTasks","summary":"List tasks.","description":"List open tasks and reminders from CortexPlus.","x-openai-isConsequential":false,"parameters":[{"name":"status","in":"query","description":"Task status to filter by.","schema":{"type":"string","default":"open"}},{"name":"client","in":"query","description":"Client name or slug to filter by.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of tasks to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["tasks"],"properties":{"tasks":{"type":"array","items":{"type":"object","required":["id","title","client","status","dueAt","url"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"client":{"type":["string","null"]},"status":{"type":["string","null"]},"dueAt":{"type":["string","null"]},"url":{"type":"string","format":"uri"}}}}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":"string"}},"required":["error"]}}}}}}}}}