Captures API

Manage captures programmatically

The Captures API allows you to create, read, update, and delete captures in your Clear Tangle account. Captures are automatically processed by AI to generate summaries, tags, categories, and Smart search embeddings.

Endpoints

Method	Endpoint	Description
`GET`	`/captures`	List all captures
`POST`	`/captures`	Create a capture
`GET`	`/captures/:id`	Get a capture
`PATCH`	`/captures/:id`	Update a capture
`DELETE`	`/captures/:id`	Delete a capture
`GET`	`/captures/search`	Search captures

Create a Capture

Create a new capture. The API automatically processes the content to generate AI summaries, extract tags, and create Smart search embeddings. Tasks mentioned in the content are automatically extracted.

Request

curl -X POST "https://api.cleartangle.com/captures" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Meeting notes: Discussed Q1 roadmap with team. Action items: finalize budget by Friday.",
    "tags": ["meeting", "planning"],
    "projectId": "proj_123456",
    "metadata": {
      "source": "api",
      "importance": "high"
    }
  }'

Request Body

Field	Type	Required	Description
`content`	string	Yes	The capture content (max 50,000 chars)
`tags`	string[]	No	Array of tags to apply
`projectId`	string	No	Project to associate with
`metadata`	object	No	Custom metadata key-value pairs
`skipAiProcessing`	boolean	No	Skip AI processing (default: false)

Response

{
  "success": true,
  "data": {
    "id": "cap_789xyz",
    "content": "Meeting notes: Discussed Q1 roadmap with team. Action items: finalize budget by Friday.",
    "summary": "Q1 roadmap meeting with budget action item",
    "tags": ["meeting", "planning"],
    "projectId": "proj_123456",
    "category": "work",
    "embedding": [...],
    "extractedTasks": [
      {
        "id": "task_abc123",
        "title": "Finalize budget",
        "dueDate": "2024-01-19"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

AI Processing

By default, all captures are processed by AI to extract summaries, tags, and tasks. Set skipAiProcessing: true if you want to bypass this for bulk imports.

List Captures

Retrieve a paginated list of captures with optional filtering.

curl -X GET "https://api.cleartangle.com/captures?limit=20&page=1&tags=meeting" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`tags`	string	Comma-separated tag filter
`projectId`	string	Filter by project
`category`	string	Filter by category
`startDate`	ISO8601	Filter by creation date (from)
`endDate`	ISO8601	Filter by creation date (to)
`sort`	string	Sort field (createdAt, updatedAt)
`order`	string	Sort order (asc, desc)

Search Captures

Search captures using keyword or Smart search. Smart search uses AI embeddings to find conceptually similar content.

curl -X GET "https://api.cleartangle.com/captures/search?q=budget+roadmap&semantic=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search Parameters

qSearch query string

semanticEnable Smart search (true/false, default: false)

thresholdSimilarity threshold for Smart search (0-1, default: 0.7)

limitMaximum results (default: 20)

Update a Capture

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

curl -X PATCH "https://api.cleartangle.com/captures/cap_789xyz" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["meeting", "planning", "important"],
    "projectId": "proj_newproject"
  }'

Updating the content field triggers AI reprocessing to update summaries and embeddings.

Delete a Capture

Permanently delete a capture. This action cannot be undone.

curl -X DELETE "https://api.cleartangle.com/captures/cap_789xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cascading Delete

Deleting a capture also deletes any tasks that were automatically extracted from it.