Quickstart

Three steps get a collection searchable: create it, index files into it, query it. This page walks through all three with the API directly. To skip straight to a working integration from your editor, use the MCP Server instead.

Prerequisites

Get Your API Credentials

You’ll need:

• API Key from Captain API Studio (format: cap_dev_..., cap_prod_...)
• Organization ID (UUID format, also available in the Studio)

Store your API key securely, such as in an environment variable:

CAPTAIN_API_KEY="cap_prod_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[1/3] Create a Collection

In order for Captain to be able to search files, we need to first create a Collection for our files to be indexed into.

This is as easy as a single API call: See the Create Collection - API Reference

$
curl -X PUT https://api.captain.dev/v2/collections/my_first_collection \
>
     -H "Authorization: Bearer $CAPTAIN_API_KEY" \
>
     -H "Content-Type: application/json" \
>
     -d '{"description": "My first Captain Collection"}'

After the collection is created, we should get a response like this:

1
{
2
  "collection_name": "my_first_collection",
3
  "collection_id": "019e94e8-3b50-74d7-9459-6ef378401335",
4
  "organization_id": "019ae889e89efd0029a25d559fda8cd4e3e4",
5
  "created_at": "2026-01-15T12:00:00.000000",
6
  "description": "My first Captain Collection",
7
  "metadata": null
8
}

[2/3] Index Files into Collections

Next, index files into the collection. Captain connects to ten storage sources:

The three worked examples below cover S3, GCS, and Azure. The same processing_type and job-polling pattern carries over to every other connector; see Connect Cloud Storage for setup on each one.

Beyond cloud storage, Captain also reads from Notion, Slack, Snowflake, Linear, Jira, and more. See Integrations for the full list.

For a collection that stays matched to a bucket over time instead of a one-off index call, see Set Up Sync after finishing this walkthrough.

Option A: Index AWS S3 Bucket

See the Index S3 Bucket - API Reference

Need AWS credentials? See the Connect Cloud Storage Guide for step-by-step instructions.

$
curl -X POST https://api.captain.dev/v2/collections/my_first_collection/index/s3 \
>
     -H "Authorization: Bearer $CAPTAIN_API_KEY" \
>
     -H "Content-Type: application/json" \
>
     -d '{
>
       "bucket_name": "my-s3-bucket",
>
       "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
>
       "aws_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
>
       "bucket_region": "us-east-1",
>
       "processing_type": "advanced"
>
     }'

Option B: Index Google Cloud Storage Bucket

See the Index GCS Bucket - API Reference

Need GCS credentials? See the Connect Cloud Storage Guide for step-by-step instructions.

$
curl -X POST https://api.captain.dev/v2/collections/my_first_collection/index/gcs \
>
     -H "Authorization: Bearer $CAPTAIN_API_KEY" \
>
     -H "Content-Type: application/json" \
>
     -d '{
>
       "bucket_name": "my-gcs-bucket",
>
       "service_account_json": "{\"type\":\"service_account\",\"project_id\":\"...\"}",
>
       "processing_type": "advanced"
>
     }'

Option C: Index Azure Blob Storage

See the Index Azure Container - API Reference

$
curl -X POST https://api.captain.dev/v2/collections/my_first_collection/index/azure \
>
     -H "Authorization: Bearer $CAPTAIN_API_KEY" \
>
     -H "Content-Type: application/json" \
>
     -d '{
>
       "container_name": "my-container",
>
       "account_name": "mystorageaccount",
>
       "account_key": "your_account_key_base64",
>
       "processing_type": "advanced"
>
     }'

Monitor Indexing Progress

See the Get Job Status - API Reference

1
import time
2
3
while True:
4
    response = requests.get(
5
        f"{BASE_URL}/v2/jobs/{job_id}",
6
        headers={"Authorization": f"Bearer {API_KEY}"}
7
    )
8
9
    result = response.json()
10
    status = result.get('status')
11
    progress = result.get('progress_message', '')
12
    print(f"Status: {status} - {progress}")
13
14
    if status in ['completed', 'completed_with_errors', 'failed', 'cancelled', 'timed_out']:
15
        if status in ['completed', 'completed_with_errors']:
16
            print("Indexing complete!")
17
            final = result.get('result', {})
18
            print(f"Files indexed: {final.get('files_indexed', 0)}")
19
        break
20
21
    time.sleep(5)

[3/3] Querying Collections

Once your files are indexed, query the collection to retrieve source chunks. See the Query Collection - API Reference or the File Search API guide.

Deterministic File Search

$
curl -X POST https://api.captain.dev/v2/collections/my_first_collection/query \
>
     -H "Authorization: Bearer $CAPTAIN_API_KEY" \
>
     -H "Content-Type: application/json" \
>
     -d '{
>
       "query": "What are the revenue projections for Q4?",
>
       "top_k": 20,
>
       "rerank": true
>
     }'

Use v3 when you want region records, chunk relations, hydrated related_chunks, or text instead of v2 content.

Other Info

Environment Scoping

API keys are scoped to environments:

• Development (cap_dev_*) - For testing and development
• Staging (cap_stage_*) - For pre-production testing
• Production (cap_prod_*) - For production use

Collections created with a development key can only be accessed with development keys from the same organization.

Supported File Types

Captain indexes 30+ file types: documents, images, video, and audio. See Supported File Types for the full extension list and the File Size Limits page for the ceiling on each type.

What Else Captain Does

• MCP Server: connect Captain to Claude, Cursor, or any MCP client without writing API calls by hand. See MCP Server.
• Sync: keep a collection matched to a bucket automatically, with backfills, reconciliation, and webhooks on file changes. See Set Up Sync.
• PII Masking: redact names, IDs, and other sensitive text and faces before content is indexed. See PII Masking.
• v3 Query: the preferred query path for new applications, with region records, chunk relations, and hydrated related_chunks. See the File Search API guide.

Getting Help

Need assistance? We’re here to help!

• Email: humans@captain.dev
• Documentation: docs.captain.dev

Send Feedback

Captain wants your feedback - both while you build and while Captain runs live inside your application or agent. No API key required.

Send feedback when you:

• Finish building an integration - tell us what was smooth or rough.
• Hit a solid, server-side Captain roadblock - an endpoint that errored, behaved unexpectedly, or blocked you with no clean workaround. Include what you tried.
• Want to shape the product - suggest a feature, flag a missing capability, or weigh in on direction. Welcome anytime, in development or in production.
• Run into confusing or incorrect docs, or any friction worth flagging.

POST https://api.captain.dev/feedback with a plain-text body:

$
curl -X POST "https://api.captain.dev/feedback?agent=my-agent&source=quickstart" \
>
  -H "Content-Type: text/plain" \
>
  --data "Finished the S3 integration. Roadblock: /index/s3 returned 500 on a 50k-object bucket with no pagination guidance. Feature request: a dry-run to validate IAM before indexing."

Optional metadata via query params or X-Feedback-* headers: agent (your tool/agent name), client_version, and source (the page or endpoint your feedback is about). The endpoint is rate-limited per IP, so keep each submission focused on one clear issue. This is the fastest way for AI agents and developers to flag friction while it’s fresh.