API Reference

Base URL: https://api.runcaptain.com

Authentication

All API requests require authentication using your API key and organization ID.

Authorization: Bearer YOUR_API_KEY

Most endpoints also require api_key and organization_id in the request body.

Create Database

Creates a new database for indexing files.

Endpoint

POST /api/v1/create-database

Parameters

Parameter	Type	Required	Description
`database_name`	string	Yes	Unique name for your database. Must be unique within your account.
`api_key`	string	Yes	Your Captain API key
`organization_id`	string	Yes	Your organization UUID

Request Example

import requests

response = requests.post(
    "https://api.runcaptain.com/api/v1/create-database",
    data={
        'organization_id': '01999eb7-8554-5c7b-6321-066454166af2',
        'api_key': 'cap_dev_NvXocMo6ZrqsVgAKR6ofIB8TtwbdSBfd',
        'database_name': 'my_documents'
    }
)

print(response.json())

Response

Success (200 OK)

{
  "database_name": "my_documents",
  "database_id": "db_abc123",
  "status": "success",
  "message": "Database created successfully"
}

Error (400 Bad Request)

{
  "status": "error",
  "message": "Database name already exists"
}

Notes

Database names are scoped to your organization account
Two different organizations can use the same database name but only one database of a certain name can be created within an organization.
Special characters and spaces should be avoided in database names

Delete Database

Deletes a database. This cannot be undone.

Endpoint

POST /api/v1/delete-database

Parameters

Parameter	Type	Required	Description
`database_name`	string	Yes	Name of the database to delete
`api_key`	string	Yes	Your Captain API key
`organization_id`	string	Yes	Your organization UUID

Request Example

import requests

response = requests.post(
    "https://api.runcaptain.com/api/v1/delete-database",
    data={
        'organization_id': '01999eb7-8554-5c7b-6321-066454166af2',
        'api_key': 'cap_dev_NvXocMo6ZrqsVgAKR6ofIB8TtwbdSBfd',
        'database_name': 'my_documents'
    }
)

print(response.json())

Response

Success (200 OK)

{
  "status": "success",
  "message": "Database deleted successfully",
  "database_name": "my_documents"
}

Error (404 Not Found)

{
  "status": "error",
  "message": "Database not found"
}

Error (401 Unauthorized)

{
  "status": "error",
  "message": "Invalid API key"
}

Notes

This action cannot be undone.
All indexed files in the database are deleted as well.
You may create a new database with the same name after deletion .

List Databases

Retrieves all databases associated with your account.

Endpoint

POST /api/v1/list-databases

Parameters

Parameter	Type	Required	Description
`api_key`	string	Yes	Your Captain API key
`organization_id`	string	Yes	Your organization UUID

Request Example

import requests

headers = {
    "Authorization": "Bearer cap_dev_NvXocMo6ZrqsVgAKR6ofIB8TtwbdSBfd",
    "Content-Type": "application/x-www-form-urlencoded"
}

response = requests.post(
    "https://api.runcaptain.com/api/v1/list-databases",
    headers=headers,
    data={
        'api_key': 'cap_dev_NvXocMo6ZrqsVgAKR6ofIB8TtwbdSBfd',
        'organization_id': '01999eb7-8554-5c7b-6321-066454166af2'
    }
)

print(response.json())

Response

Success (200 OK)

[
  {
    "database_id": "db_abc123",
    "database_name": "contracts_2024",
    "environment": "production",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "request_count": 1250
  },
  {
    "database_id": "db_def456",
    "database_name": "research_docs",
    "environment": "production",
    "is_active": true,
    "created_at": "2024-02-01T14:20:00Z",
    "request_count": 487
  }
]

Empty Response (200 OK)

[]

Response Fields

Field	Type	Description
`database_id`	string	Unique identifier for the database
`database_name`	string	Name of the database
`environment`	string	Environment scope of the database
`is_active`	boolean	Whether the database is active
`created_at`	string	ISO 8601 timestamp of creation
`request_count`	integer	Number of queries made to this database

Notes

This list is limited to 1,000 databases. If you need a higher count, please contact us at support@runcaptain.com or call us at +1 (260) CAP-TAIN.

Index S3 Bucket

Start indexing all files from an S3 bucket into your database.

Endpoint

POST /api/v1/index-all

Parameters

Parameter	Type	Required	Description
`database_name`	string	Yes	Target database name
`bucket_name`	string	Yes	S3 bucket name
`aws_access_key_id`	string	Yes	AWS access key ID
`aws_secret_access_key`	string	Yes	AWS secret access key (URL-encoded)
`bucket_region`	string	Yes	S3 bucket region (e.g., `us-east-1`)
`api_key`	string	Yes	Your Captain API key
`organization_id`	string	Yes	Your organization UUID

Request Example

import requests
from urllib.parse import quote

aws_secret = "your_aws_secret_key"
aws_secret_encoded = quote(aws_secret, safe='')

response = requests.post(
    "https://api.runcaptain.com/api/v1/index-all",
    data={
        'database_name': 'contracts_2024',
        'bucket_name': 'my-company-docs',
        'aws_access_key_id': 'AKIAIOSFODNN7EXAMPLE',
        'aws_secret_access_key': aws_secret_encoded,
        'bucket_region': 'us-east-1',
        'api_key': 'cap_dev_NvXocMo6ZrqsVgAKR6ofIB8TtwbdSBfd',
        'organization_id': '01999eb7-8554-5c7b-6321-066454166af2'
    },
    timeout=30.0
)

print(response.json())

Response

Success (200/201)

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "message": "Indexing job started successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}

Error (400 Bad Request)

{
  "status": "error",
  "message": "Unsupported file type detected",
  "details": "File 'video.mp4' is not supported"
}

Indexing Behavior

Important: This endpoint wipes all previously indexed files from the database and then indexes all files from the bucket.

Supported File Types

Captain uses an allow-list for supported file types:

Documents

PDF (.pdf) - Up to 512MB with automatic page chunking
Microsoft Word (.docx)
Text files (.txt)
Markdown (.md)

Spreadsheets & Data

Microsoft Excel (.xlsx, .xls) - With intelligent row-based chunking
CSV (.csv) - With header preservation across chunks
JSON (.json)

Presentations

Microsoft PowerPoint (.pptx, .ppt)

Images (with OCR and Computer Vision support)

JPEG (.jpg, .jpeg)
PNG (.png)
BMP (.bmp) (Experimental)
GIF (.gif) (Experimental)
TIFF (.tiff) (Experimental)

Code

Python (.py)
TypeScript (.ts)
JavaScript (.js)
HTML (.html)
CSS (.css)
PHP (.php)
Java (.java)

Unsupported types (.mov, .mp4, .avi, etc.) will individually fail but the rest of the files will be indexed.

Check Indexing Status

Retrieves the status of an indexing job. Polling this endpoint is the recommended way to check the status of an indexing job.

Endpoint

GET /api/v1/indexing-status/{job_id}

Parameters

Path Parameters:

Parameter	Type	Required	Description
`job_id`	string	Yes	Job ID returned from index-all endpoint

Request Example

import requests

job_id = "job_abc123xyz"

headers = {
    "Authorization": "Bearer cap_dev_NvXocMo6ZrqsVgAKR6ofIB8TtwbdSBfd",
    "Content-Type": "application/json"
}

response = requests.get(
    f"https://api.runcaptain.com/api/v1/indexing-status/{job_id}",
    headers=headers
)

print(response.json())

Response

In Progress

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "completed": false,
  "active_file_processing_workers": 8,
  "timestamp": "2024-01-15T10:35:00Z",
  "job_details": {
    "job_name": "index_contracts_2024",
    "total_files": 1000,
    "indexed_files": 342,
    "failed_files": 3
  }
}

Completed

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "completed": true,
  "active_file_processing_workers": 0,
  "timestamp": "2024-01-15T11:05:00Z",
  "job_details": {
    "job_name": "index_contracts_2024",
    "total_files": 1000,
    "indexed_files": 997,
    "failed_files": 3
  }
}

Error

{
  "job_id": "job_abc123xyz",
  "status": "error",
  "completed": true,
  "error": "AWS credentials invalid",
  "timestamp": "2024-01-15T10:32:00Z"
}

Polling Recommendations

Poll every 3 seconds (industry standard)
Check for completed: true or status: "completed", "error", or "failed"
Monitor active_file_processing_workers to gauge progress, although usually this just says 0 and then jumps to all at the end.
Calculate progress: (indexed_files + failed_files) / total_files * 100

Query Database

Query your indexed data using natural language.

Endpoint

POST /api/v1/query

Headers

Header	Required	Description
`Authorization`	Yes	Bearer token: `Bearer {api_key}`
`Content-Type`	Yes	Must be `application/x-www-form-urlencoded`
`X-Organization-ID`	Yes	Your organization UUID
`Idempotency-Key`	No	Unique UUID for request deduplication (recommended)

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Natural language query (URL-encoded)
`database_name`	string	Yes	Database to query
`include_files`	boolean	No	Include file metadata in response (default: false)

Request Example

import requests
import uuid
from urllib.parse import quote

query = "find Q3 contracts mentioning 'termination for convenience'"
idempotency_key = str(uuid.uuid7())

headers = {
    "Authorization": "Bearer cap_dev_NvXocMo6ZrqsVgAKR6ofIB8TtwbdSBfd",
    "Content-Type": "application/x-www-form-urlencoded",
    "X-Organization-ID": "01999eb7-8554-5c7b-6321-066454166af2"
    "Idempotency-Key": idempotency_key,
}

response = requests.post(
    "https://api.runcaptain.com/api/v1/query",
    headers=headers,
    data={
        'query': quote(query),
        'database_name': 'contracts_2024',
        'include_files': 'true'
    },
    timeout=120.0
)

print(response.json())

Response

Success (200 OK)

{
  "status": "success",
  "response": "Based on your Q3 contracts, three documents mention 'termination for convenience' clauses. The Acme Corp contract (Section 12.3) allows either party to terminate with 30 days notice. The Beta Industries agreement (Section 8.1) specifies 60 days notice for convenience termination...",
  "relevant_files": [
    {
      "file_name": "Acme_Corp_Q3_2024.pdf",
      "relevancy_score": 0.92,
      "file_type": "pdf",
      "file_id": "0199bc97-212f-729a-9c0b-cc23f21e0995"
    },
    {
      "file_name": "Beta_Industries_Contract.pdf",
      "relevancy_score": 0.87,
      "file_type": "pdf",
      "file_id": "0199bc97-20c9-770e-95f9-3fee32ab9b14"
    }
  ],
  "query": "find Q3 contracts mentioning 'termination for convenience'",
  "database_name": "contracts_2024",
  "processing_metrics": {
    "total_files_processed": 4,
    "total_tokens": 16308,
    "execution_time_ms": 1250
  }
}

Note: When include_files=false (default), the relevant_files array is omitted from the response to reduce payload size.

Response Fields

Field	Type	Description
`status`	string	Request status
`response`	string	Natural language answer to your query
`relevant_files`	array	Array of relevant file objects (if `include_files: true`)
`query`	string	Echo of your original query
`database_name`	string	Database that was queried

Relevant Files Object:

Field	Type	Description
`file_name`	string	Name of the file
`relevancy_score`	float	Relevancy score (0.0 - 1.0)
`file_type`	string	File extension/type (e.g., "pdf", "py", "docx")
`file_id`	string	Unique identifier for the file

Processing Metrics Object:

Field	Type	Description
`total_files_processed`	integer	Number of files analyzed
`total_tokens`	integer	Total tokens processed
`execution_time_ms`	integer	Query execution time in milliseconds

Notes

Query timeout is 120 seconds
The response field contains the answer with inline references
Idempotency-Key prevents duplicate processing of the same request (minimizing costs)

Error Responses

All endpoints follow consistent error response formats:

400 Bad Request

{
  "status": "error",
  "message": "Invalid parameter: database_name is required"
}

401 Unauthorized

{
  "status": "error",
  "message": "Invalid or expired API key"
}

403 Forbidden

{
  "status": "error",
  "message": "API key does not belong to this organization"
}

404 Not Found

{
  "status": "error",
  "message": "Database not found"
}

500 Internal Server Error

{
  "status": "error",
  "message": "Internal server error",
  "details": "Contact support if this persists"
}

Rate Limits

Rate limits are applied per API key. Contact support for specific limits on your account.

Support

For API support, contact: support@runcaptain.com or call us at +1 (260) CAP-TAIN.