M
Give Moltbot superpowered memory with one command
Install Now

API Reference

Complete reference for the Onelist REST API. Build integrations, sync data, and extend Onelist with your own applications.

Authentication

All API requests require authentication using an API key. You can generate API keys from your account settings in the Onelist dashboard.

Keep your API keys secure

Never expose API keys in client-side code or public repositories. Use environment variables and server-side requests.

Bearer Token Authentication

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer your_api_key_here

Example Request

# Authenticate with Bearer token
curl https://api.onelist.my/v1/entries \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Base URL

All API endpoints are relative to the following base URL:

https://api.onelist.my/v1

For self-hosted instances, replace this with your own API endpoint.

Rate Limiting

API requests are rate limited to ensure fair usage and system stability.

Plan Rate Limit Burst
Free 100 requests/minute 20 requests
Pro 1,000 requests/minute 100 requests
Team 5,000 requests/minute 500 requests

Rate Limit Headers

Each response includes headers to help you track your rate limit status:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Error Responses

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error Format

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is missing required fields",
    "details": {
      "missing_fields": ["title"]
    }
  }
}

HTTP Status Codes

Status Description
200 Success
201 Created - Resource successfully created
400 Bad Request - Invalid parameters or request body
401 Unauthorized - Invalid or missing API key
403 Forbidden - API key lacks required permissions
404 Not Found - Resource does not exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Entries

GET /entries

Retrieve a paginated list of entries. Supports filtering by tags, date range, and search query.

Query Parameters

Parameter Type Description
page integer Page number (default: 1)
per_page integer Items per page (default: 20, max: 100)
tag_ids string Comma-separated tag IDs to filter by
created_after string ISO 8601 datetime filter
created_before string ISO 8601 datetime filter
sort string Sort field: created_at, updated_at, title
order string Sort order: asc or desc

Example

# List entries with filters
curl "https://api.onelist.my/v1/entries?page=1&per_page=20&tag_ids=123,456" \
  -H "Authorization: Bearer your_api_key"
POST /entries

Create a new entry with optional tags and representations.

Request Body

{
  "title": "My New Entry",
  "content": "The main content of the entry...",
  "tag_ids": ["tag_123", "tag_456"],
  "metadata": {
    "source": "api",
    "priority": "high"
  }
}

Example

# Create a new entry
curl -X POST https://api.onelist.my/v1/entries \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting Notes",
    "content": "Discussed Q4 roadmap and priorities...",
    "tag_ids": ["work", "meetings"]
  }'
GET /entries/:id

Retrieve a single entry by its ID, including all representations and tags.

Example

# Get a specific entry
curl https://api.onelist.my/v1/entries/entry_abc123 \
  -H "Authorization: Bearer your_api_key"

Response

{
  "id": "entry_abc123",
  "title": "Meeting Notes",
  "content": "Discussed Q4 roadmap...",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T14:22:00Z",
  "tags": [
    {"id": "tag_123", "name": "work"}
  ],
  "representations": [...]
}
PATCH /entries/:id

Update an existing entry. Only provided fields will be updated.

Example

# Update an entry
curl -X PATCH https://api.onelist.my/v1/entries/entry_abc123 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Meeting Notes",
    "tag_ids": ["work", "meetings", "important"]
  }'
DELETE /entries/:id

Permanently delete an entry and all its representations.

Example

# Delete an entry
curl -X DELETE https://api.onelist.my/v1/entries/entry_abc123 \
  -H "Authorization: Bearer your_api_key"

Tags

GET /tags

Retrieve all tags for the authenticated user.

Example

# List all tags
curl https://api.onelist.my/v1/tags \
  -H "Authorization: Bearer your_api_key"

Response

{
  "tags": [
    {
      "id": "tag_123",
      "name": "work",
      "color": "#2563EB",
      "entry_count": 42
    },
    {
      "id": "tag_456",
      "name": "personal",
      "color": "#10B981",
      "entry_count": 28
    }
  ]
}
POST /tags

Create a new tag.

Example

# Create a new tag
curl -X POST https://api.onelist.my/v1/tags \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects",
    "color": "#8B5CF6"
  }'
PATCH /tags/:id

Update an existing tag's name or color.

Example

# Update a tag
curl -X PATCH https://api.onelist.my/v1/tags/tag_123 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "work-projects", "color": "#DC2626"}'
DELETE /tags/:id

Delete a tag. Entries with this tag will not be deleted, but the tag will be removed from them.

Example

# Delete a tag
curl -X DELETE https://api.onelist.my/v1/tags/tag_123 \
  -H "Authorization: Bearer your_api_key"

Search

POST /search

Full-text search across all entries. Supports advanced query syntax, filters, and relevance scoring.

Request Body

Field Type Description
query string Search query (required)
tag_ids array Filter by tag IDs
date_from string ISO 8601 date filter
date_to string ISO 8601 date filter
limit integer Max results (default: 20, max: 100)

Example

# Search entries
curl -X POST https://api.onelist.my/v1/search \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "meeting notes Q4",
    "tag_ids": ["work"],
    "limit": 10
  }'

Response

{
  "results": [
    {
      "id": "entry_abc123",
      "title": "Q4 Planning Meeting Notes",
      "snippet": "...discussed the Q4 roadmap and meeting...",
      "score": 0.95,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 15,
  "query_time_ms": 12
}

Representations

Representations are different views or formats of an entry's content. Each entry can have multiple representations (e.g., markdown, plain text, HTML, summary).

GET /entries/:entry_id/representations

List all representations for a specific entry.

Example

# List representations for an entry
curl https://api.onelist.my/v1/entries/entry_abc123/representations \
  -H "Authorization: Bearer your_api_key"
GET /entries/:entry_id/representations/:id

Get a specific representation by ID.

Example

# Get a specific representation
curl https://api.onelist.my/v1/entries/entry_abc123/representations/rep_xyz789 \
  -H "Authorization: Bearer your_api_key"

Response

{
  "id": "rep_xyz789",
  "entry_id": "entry_abc123",
  "type": "markdown",
  "content": "# Meeting Notes\n\n## Attendees\n...",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
POST /entries/:entry_id/representations

Create a new representation for an entry.

Request Body

{
  "type": "summary",
  "content": "A brief summary of the entry...",
  "metadata": {
    "generated_by": "ai",
    "model": "gpt-4"
  }
}

Example

# Create a new representation
curl -X POST https://api.onelist.my/v1/entries/entry_abc123/representations \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "summary",
    "content": "Key discussion points from Q4 planning..."
  }'
PATCH /entries/:entry_id/representations/:id

Update an existing representation.

Example

# Update a representation
curl -X PATCH https://api.onelist.my/v1/entries/entry_abc123/representations/rep_xyz789 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated summary content..."}'