API reference

Every endpoint of the Ultrathink REST API. Start with API: getting started for keys, limits and errors.

All paths are relative to https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1, and every request needs Authorization: Bearer YOUR_DEVICE_KEY. Replies wrap their result in data, as described on the getting started page.

The entry object

Every endpoint that returns entries returns them in this shape.

GET /entries

Lists your own entries, newest first unless you sort otherwise.

The reply’s data has items (entry objects) and pagination with page, limit, total, totalPages, hasMore and nextCursor (null on the last page).

Filters that work together

• No filters, with any sort and order.
• Any one or two filters with the default sort (createdAt, newest first).
• topics and a due date range, with type or entity as well.
• topics with sort=createdAt or sort=updatedAt, in either order.
• A due date range with any sort. More than 2,000 entries due in the range returns a 400.
• entity with sort=due_date&order=asc, for example tasks by due date.
• taskStatus or done on their own with sort=createdAt, with sort=due_date&order=asc, or with a due date range.
• taskStatus or done with topics or entity, using the default sort, sort=due_date&order=asc or a due date range.
• externalId with the default sort.
• person on its own or with entity, in either order.
• waitingOn on its own or with entity, also with sort=due_date&order=asc.
• updatedSince on its own, or with one of entity, type, topics or person. Not with a due date range, or a sort other than updatedAt.

Other combinations may return a 400 saying the combination is not supported. Use fewer filters, or the default sort.

curl -H "Authorization: Bearer YOUR_DEVICE_KEY" \
  "https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1/entries?waitingOn=me&entity=task&sort=due_date&order=asc"

GET /entries/{id}

Reads one entry: one of yours, or one another member shared with your organisation (owned is then false). Every id that search returns can be read here. An entry you cannot see returns 404, the same as one that does not exist.

POST /entries

Creates an entry. Send JSON. Only title is required.

Rules:

• Only work entries can be shared. "visibility": "org" with "category": "personal" returns a 400. An entry with no category yet can be shared.
• Sharing needs you to be a member of an organisation now, otherwise 400.
• A status your workflows do not have returns a 400 listing the ones you can use.

The reply is 201 with the new entry. The AI then writes its title, summary, topics and people, as for anything you save in the app.

curl -X POST \
  -H "Authorization: Bearer YOUR_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Send Ana the report", "entity": "task", "dueDate": "2026-10-20", "dueTime": "14:30", "waitingOn": "me"}' \
  "https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1/entries"

PATCH /entries/{id}

Changes one of your own entries. Send only the fields you want to change; they are the same as for POST /entries.

• taskStatus: null clears the status. Changing the status never moves the entry to another kanban column: columns are independent of status.
• topics replaces the whole list. AI topics you keep stay AI topics, and the AI does not add back the ones you leave out.
• aiTopics: false takes the AI’s topics off and stops it adding more. true lets it add them again.
• dueTime, waitingOn and webLinks are cleared with null. Clearing dueDate clears its time too. A dueTime with no due date returns a 400.
• webLinks replaces the whole list.
• Moving a shared entry out of work (for example "category": "personal") also makes it private.
• triggerAI: true runs the AI pass again. Without it, the AI does not run.

Entries shared with you by someone else cannot be changed, and return 404.

DELETE /entries/{id}

Deletes one of your own entries. It cannot be undone.

curl -X DELETE \
  -H "Authorization: Bearer YOUR_DEVICE_KEY" \
  "https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1/entries/ENTRY_ID"

The reply’s data is { "id": "ENTRY_ID", "deleted": true }. An entry that is not yours returns 404.

GET /entries/{id}/related

An entry’s similar entries, as the AI picked them when the entry was saved, and the entries you linked to it. Only entries you can read are listed.

{
  "entryId": "abc123",
  "mode": "classic",
  "similar": [
    {
      "id": "def456",
      "title": "Partner deals tracker",
      "type": "note",
      "entity": "task",
      "timestamp": "2026-08-01T10:00:00.000Z",
      "excerpt": "Deals by partner, weekly.",
      "score": null,
      "reason": "Both track partner deals",
      "duplicate": false
    }
  ],
  "links": [
    {
      "id": "ghi789",
      "title": "Call with Ana",
      "type": "note",
      "entity": "knowledge",
      "timestamp": "2026-07-01T10:00:00.000Z",
      "excerpt": "Ana wants the report in Teams.",
      "linkType": "related"
    }
  ]
}

reason says why the AI thought the entries are alike. excerpt is the first words of the entry as plain text.

GET /topics and GET /people

Your topics, or the people in your entries, each with how many entries have it, most used first.

{
  "items": [
    { "name": "planning", "count": 12 },
    { "name": "meetings", "count": 9 }
  ],
  "total": 48,
  "entriesCounted": 1311,
  "partial": false
}

total is how many names match before limit. partial is true only when you have more than 10,000 entries, and then the newest 10,000 are counted. Counts can lag a few minutes behind changes made in the app.

POST /search

Asks a question in plain words. The AI reads your most recent entries, up to the Entry limit in Settings, then AI search (500 unless you change it), and answers with the entries it used. Entries shared with your organisation are read too.

{
  "answer": "You agreed to move the pricing page launch to November.",
  "mode": "classic",
  "matches": [
    {
      "id": "abc123",
      "title": "Pricing page review",
      "type": "note",
      "entity": "project",
      "timestamp": "2026-10-02T09:15:00.000Z",
      "source": "user",
      "score": null,
      "cited": true,
      "excerpt": "Launch moves to November so the copy can be checked..."
    }
  ],
  "entryCount": 500,
  "durationMs": 2100
}

Search only sees the entries inside your entry limit. To find something older, filter with GET /entries instead.

POST /upload

Uploads a file and returns its address. It does not create an entry by itself.

Send it as multipart/form-data with the file in a field called file, and give the file’s type, as the API checks it:

curl -X POST \
  -H "Authorization: Bearer YOUR_DEVICE_KEY" \
  -F "file=@meeting.m4a;type=audio/mp4" \
  "https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1/upload"

Or as JSON, with the file as a data URL:

{ "file": "data:application/pdf;base64,JVBERi0...", "filename": "report.pdf" }

A request over about 32 MB fails before it reaches Ultrathink, whatever the file. Upload large recordings and videos from the web app or the desktop app instead.

The reply is 201:

{
  "url": "https://firebasestorage.googleapis.com/v0/b/...",
  "path": "user-uploads/USER_ID/audio/1760440000000-ab12cd34.m4a",
  "mimeType": "audio/mp4",
  "size": 4823011,
  "category": "audio"
}

Entry types

These are the values type takes.

OpenAPI file

The same API is described in an OpenAPI file, which you can import into Postman, Insomnia or a ChatGPT custom GPT:

https://tryultrathink.com/docs/api/openapi.yaml