API access

Ultrathink provides a REST API that gives you programmatic access to your knowledge base. Use it to build custom integrations, automate workflows, or connect third-party tools to your entries.

Authentication

All API requests require a device key with API access enabled. The key is passed as a Bearer token in the Authorization header.

Creating a device key

1. Sign in to tryultrathink.com
2. Go to Settings, then Device Keys
3. Click Create New Key
4. Give the key a descriptive name (for example, "API automation")
5. Enable API Access
6. Set permissions:
   • Read: list, search, and retrieve entries
   • Write: create and update entries
   • Read+Write: full access
7. Copy the key immediately; it is only shown once

Note: API access requires a Pro plan subscription.

Using the key

Include the key in the Authorization header of every request:

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

Base URL

All API endpoints use the following base URL:

https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1

Rate limits

The API enforces rate limits per device key to ensure fair usage:

Endpoint	Method	Limit
/entries	GET	60 requests per minute
/entries/:id	GET	120 requests per minute
/entries	POST	30 requests per minute
/entries/:id	PATCH	30 requests per minute
/search	POST	15 requests per minute
/upload	POST	20 requests per minute

Rate limit information is included in response headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	When the window resets (ISO 8601 timestamp)

When you exceed a rate limit, the API returns a 429 status code with a retryAfter value in the response body indicating how many seconds to wait.

Endpoints overview

List entries

GET /entries

Returns a paginated list of entries from your knowledge base.

Query parameters:

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	20	Entries per page (max 100)
type	string		Filter by entry type (link, note, chatgpt, claude, etc.)
entity	string		Filter by entity (project, task, knowledge)
topics	string		Comma-separated topic names
sort	string	createdAt	Sort field (createdAt, updatedAt, title)
order	string	desc	Sort order (asc, desc)

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1/entries?limit=5&type=note&sort=updatedAt"

Get a single entry

GET /entries/:id

Returns the full details of a specific entry by its ID.

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1/entries/abc123"

Create an entry

POST /entries

Creates a new entry in your knowledge base.

Required fields:

Field	Type	Description
title	string	Entry title (max 500 characters)

Optional fields:

Field	Type	Description
type	string	Entry type (link, note, etc.)
entity	string	Entity classification (project, task, knowledge)
notes	string	Your notes (max 50,000 characters)
url	string	Source URL
topics	array	Topic names as strings
people	array	People names as strings
category	string	"work" or "personal"
dueDate	string	ISO 8601 date (for task entries)

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API integration notes",
    "type": "note",
    "entity": "knowledge",
    "notes": "Documentation for the new REST API integration",
    "topics": ["api", "integrations"]
  }' \
  "https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1/entries"

Update an entry

PATCH /entries/:id

Updates an existing entry. Only include the fields you want to change.

Example:

curl -X PATCH \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Updated with new findings", "topics": ["api", "integrations", "automation"]}' \
  "https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1/entries/abc123"

Search entries

POST /search

Performs AI-powered semantic search across your knowledge base.

Request body:

Field	Type	Default	Description
query	string		Natural language search query (required)
entity	string		Filter results by entity type
limit	number	10	Maximum number of results

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "React hooks best practices", "limit": 5}' \
  "https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1/search"

Response:

{
  "answer": "You have several entries about React hooks...",
  "entries": [
    {
      "id": "abc123",
      "title": "React hooks best practices",
      "relevance": 0.95,
      "snippet": "...useCallback for memoising expensive computations..."
    }
  ]
}

Upload a file

POST /upload

Uploads a file to attach to entries.

• Content type: multipart/form-data
• Field name: file
• Maximum file size: 50 MB

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@document.pdf" \
  "https://us-central1-ultrathink-50f7f.cloudfunctions.net/api/v1/upload"

Error responses

The API returns standard HTTP status codes with a JSON error body:

Status code	Meaning
400	Bad request (invalid input or missing required fields)
401	Unauthorised (invalid or missing device key)
403	Forbidden (insufficient permissions on the device key)
404	Not found (entry does not exist)
429	Rate limited (too many requests)
500	Server error (unexpected failure)

Error response format:

{
  "error": "Rate limit exceeded",
  "retryAfter": 45
}

The retryAfter field is only present on 429 responses and indicates the number of seconds to wait before retrying.

Best practices

• Store your device key securely: treat it like a password; do not commit it to version control or share it publicly
• Use Read-only keys when possible: if your integration only needs to search and retrieve entries, use a Read-only key to limit risk
• Handle rate limits gracefully: check the X-RateLimit-Remaining header and back off when it approaches zero
• Paginate large result sets: use the page and limit parameters to avoid fetching more data than you need
• Use semantic search over list+filter: the /search endpoint uses AI to find relevant entries even when exact keywords do not match

Further reading

For the full OpenAPI specification, see:

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

This spec can be imported into tools like Postman, Insomnia, or used to generate client libraries in your preferred programming language.