indexing

Index Dropbox Directory

Changed on

Index all files from a specific folder in a Dropbox account into a collection.

Headers:

  • Authorization: Bearer {api_key} - Captain API key for authentication
  • X-Organization-ID: Organization UUID
  • Idempotency-Key: UUID for request deduplication (optional)

Args: collection_name: Name of the collection (path parameter) body: Dropbox directory configuration with directory_path

Returns: { job_id, status: "pending" }

post/v2/collections/{collection_name}/index/dropbox/directory

Request

  • Base URL
    https://api.captain.dev
  • URL
    https://api.captain.dev/v2/collections/{collection_name}/index/dropbox/directory
  • Auth
    none declared

Path parameters

collection_namestring required

Headers

authorizationstring nullable

Request body

custom_metadataobject nullable

Custom metadata to attach to all indexed chunks. Keys must be strings. Values: str, int, float, bool, or List[str].

directory_pathstring required

Path to a folder within the Dropbox account (e.g. '/Reports/2024'). All files within this folder and its subfolders are indexed recursively.

dropbox_access_tokenstring required

Dropbox access token with files.metadata.read and files.content.read scopes. Generate one from the Dropbox App Console (Settings tab -> Generated access token). Tokens are short-lived and scoped to the token owner's account, ideal for one-shot indexing jobs.

max_filesinteger nullable
overwrite_existingboolean

When true, files that already exist in the collection are re-indexed and replaced with zero downtime: the new version is built alongside the live one and atomically swapped in when complete, so the previous version keeps serving search results throughout the rebuild. The document keeps the same document_id across overwrites, and its status reads 'updating' in the document listing while the rebuild runs. Requires skip_existing=false. Setting both to true returns a 400 error.

parsing_scriptstring nullable

Relative path to a JS parsing script for JSON files (e.g. 'research/paper-parser'). When provided, .json files are processed through a sandboxed V8 isolate. Without this, .json files are indexed as raw text.

processing_type'advanced' | 'basic' required

Document processing type. 'advanced' uses agentic OCR with AI-enhanced extraction for complex layouts, tables, figures, charts, and documents containing images. 'basic' provides reliable OCR optimized for general document indexing and high-volume processing.

skip_existingboolean

When true, files already indexed in the collection are skipped and will not be re-indexed with incoming changes. When false, all incoming files are indexed regardless of whether they already exist.

mask_piiboolean

When true, detected PII (emails, phone numbers, SSNs, credit cards, names, and locations) is masked in the parsed content before it is embedded and stored — replaced with entity tags like <PERSON> and <EMAIL_ADDRESS>. For images (including images embedded in PDFs), PII text visible in the image is also pixel-redacted. Opt-in; defaults to false, which leaves content unchanged.

pii_engine'kev' | 'jev' | 'presidio' | 'captain-jev' | 'captain-presidio'

Masking engine for this job. kev (default): the Kev classifier model on Captain's infrastructure; supports pii_fields and pii_instructions; no fallback, so a file kev cannot mask fails to index and the rest of the job continues. jev: TypeSafe's hosted Jev model, slightly more accurate, best-effort availability; supports custom fields and instructions and may list fallbacks in pii_fallback. presidio: the legacy pattern engine, built-in categories only (rejects pii_fields or pii_instructions with 422), never a fallback. Requires mask_pii: true. The earlier names captain-jev and captain-presidio keep working as before; new requests should use kev, jev or presidio.

pii_instructionsstring nullable

Plain-language guidance that steers what counts as personal data for this job, for the built-in categories and any pii_fields. For example: 'Names of hospital staff may stay; patient names, record numbers and bed assignments must be masked.' Requires mask_pii to be true. Up to 1,000 characters.

transcription_languagestring nullable

AWS Transcribe language code for the spoken audio (e.g. 'es-US', 'pt-BR'). Omit to auto-detect per file. Video and audio files only. Supported codes: https://docs.aws.amazon.com/transcribe/latest/dg/supported-languages.html

Response

Successful Response

job_idstring required
statusstring
custom_metadataobject nullable

The custom_metadata Captain accepted for this job, echoed back as validated. Null when none was supplied.

Changes

    • breaking

      the request property type changed from object to no type

    • warning

      removed the request property /

    • warning

      removed the request property /

    • info

      added the new captain-jev enum value to the request property

    • info

      added the new captain-presidio enum value to the request property

    • info

      added subschema #2 to the request property oneOf list

    • breaking

      removed the enum value captain-jev of the request property

    • breaking

      removed the enum value captain-presidio of the request property

    • breaking

      the request property type changed from boolean to object

    • breaking

      the response's body type changed from no type to object for status

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      the request property default value changed from captain-jev to kev

    • info

      the request property default value true was removed

    • info

      added the new jev enum value to the request property

    • info

      added the new kev enum value to the request property

    • info

      added the new presidio enum value to the request property

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status