Get Started

Quickstart

Ahoy there! Let’s get you up and running with Captain. We’ve made this quick and easy.

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:

Environment Variables
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.runcaptain.com/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:

Example: (201 Created)
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}

If the collection already exists, the call returns 200 instead of 201 with the existing collection details.

[2/3] Index Files into Collections

Next, we need to index our files into the collection.

Captain supports indexing into collections from AWS S3, Google Cloud Storage (GCS), and Azure Blob Storage via the API. You can also connect Google Drive, SharePoint, Notion, and more through the Captain Studio.

Captain Indexing API Endpoints

Every indexing request requires a processing_type field, either "advanced" or "basic". advanced uses agentic OCR with AI-enhanced extraction for complex layouts, tables, figures, and images. basic is reliable OCR optimized for general documents and high-volume processing. Omitting it returns a 422 validation error.

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.runcaptain.com/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.runcaptain.com/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.runcaptain.com/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

1import time
2
3while 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_failures', 'failed', 'cancelled']:
15        if status in ['completed', 'completed_with_failures']:
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.

$curl -X POST https://api.runcaptain.com/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 supports 30+ file types including:

Documents: PDF, DOCX, TXT, MD, RTF, ODT Spreadsheets: XLSX, XLS, CSV Presentations: PPTX, PPT Images: JPG, PNG (with OCR) Code: PY, JS, TS, HTML, CSS, PHP, JAVA Data: JSON, XML

Contact support@runcaptain.com to request file types.

More Data Sources

Beyond cloud storage, Captain connects to Google Drive, SharePoint, Notion, Slack, Snowflake, Linear, Jira, and more. See the Integrations page for the full list of supported data sources and the difference between Indexed Search and Live Search.

Getting Help

Need assistance? We’re here to help!

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.runcaptain.com/feedback with a plain-text body:

$curl -X POST "https://api.runcaptain.com/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.

© 2026 Captain