API Reference

This section provides detailed documentation for the Onsomble API.

Note

The API is currently in beta. Some endpoints may change in future releases.

Overview

The Onsomble API is a RESTful API that allows you to programmatically interact with your notebooks, sources, and conversations.

Base URL


https://api.onsomble.ai/api

Authentication

All API requests require authentication using a Bearer token:


curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.onsomble.ai/api/notebooks

Getting Your API Token

Generate an API token from your account settings at Settings → API Keys.

Quick Reference

Notebooks

Create, list, and manage notebooks

Sources

Add and manage content sources

Conversations

Create chats and send messages

Credits

Check balance and usage

Notebooks

Endpoints for managing notebooks.

List Notebooks


GET /notebooks

Returns a list of all notebooks for the authenticated user.

Response:


{
  "data": [
    {
      "id": "nb_123",
      "name": "My Research",
      "description": "Research project notes",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:45:00Z",
      "sourceCount": 5
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "perPage": 20
  }
}

Get Notebook


GET /notebooks/:id

Returns details for a specific notebook.

Create Notebook


POST /notebooks

Creates a new notebook.

Request Body:


{
  "name": "My Notebook",
  "description": "Optional description"
}

Response:


{
  "data": {
    "id": "nb_456",
    "name": "My Notebook",
    "description": "Optional description",
    "createdAt": "2024-01-21T09:00:00Z"
  }
}

Update Notebook


PATCH /notebooks/:id

Updates an existing notebook.

Delete Notebook


DELETE /notebooks/:id

Warning

Deleting a notebook also deletes all associated sources and conversations. This action cannot be undone.

Sources

Endpoints for managing sources within notebooks.

List Sources


GET /notebooks/:notebookId/sources

Returns all sources in a notebook.

Add Source


POST /notebooks/:notebookId/sources

Adds a new source to a notebook.

Request Body (File Upload):


{
  "type": "file",
  "file": "<base64-encoded-content>",
  "filename": "document.pdf"
}

Request Body (URL):


{
  "type": "url",
  "url": "https://example.com/article"
}

Request Body (YouTube):


{
  "type": "youtube",
  "url": "https://youtube.com/watch?v=..."
}

Get Source Status


GET /sources/:sourceId/status

Check the processing status of a source.

Response:


{
  "data": {
    "id": "src_789",
    "status": "completed",
    "progress": 100,
    "message": "Processing complete"
  }
}

Status	Description
`pending`	Queued for processing
`processing`	Currently being processed
`completed`	Ready for use
`failed`	Processing failed

Delete Source


DELETE /sources/:sourceId

Conversations

Endpoints for managing conversations and messages.

List Conversations


GET /notebooks/:notebookId/conversations

Returns all conversations in a notebook.

Create Conversation


POST /notebooks/:notebookId/conversations

Creates a new conversation.

Request Body:


{
  "title": "Research Questions"
}

Send Message


POST /conversations/:conversationId/messages

Sends a message and receives an AI response.

Request Body:


{
  "content": "What are the key findings from my sources?"
}

Response:


{
  "data": {
    "id": "msg_123",
    "role": "assistant",
    "content": "Based on your sources, the key findings are...",
    "citations": [
      {
        "sourceId": "src_456",
        "text": "...",
        "page": 12
      }
    ],
    "creditsUsed": 2
  }
}

Tip

Use the stream: true parameter to receive responses as a server-sent event stream for real-time display.

Credits

Get Balance


GET /credits/balance

Returns current credit balance and usage.

Response:


{
  "data": {
    "balance": 150,
    "usedThisMonth": 50,
    "resetDate": "2024-02-01T00:00:00Z"
  }
}

Error Handling

The API uses standard HTTP status codes and returns consistent error responses.

Error Response Format


{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ]
  }
}

Status Codes

Status	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing token
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limited
`500`	Internal Server Error

Rate Limiting

API requests are rate-limited to ensure fair usage.

Limit	Threshold
Per minute	100 requests
Per hour	1,000 requests
Per day	10,000 requests

Note

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

SDKs & Libraries

Coming Soon

Official SDKs for JavaScript, Python, and other languages are in development.

Need Help?

Getting Started

New to Onsomble? Start here

Core Concepts

Understand the fundamentals