Index Confluence Space

POSThttps://api.filesearch.dev/v2/collections/:collection_name/index/confluence/space

Import one Confluence space into a collection. A second call syncs: unchanged pages are skipped, changed pages are replaced and new pages are added.

Path parameters

collection_namestringRequired

Headers

authorizationstring or nullOptional

Request

This endpoint expects an object.

confluence_api_tokenstringRequired1-2048 characters

Atlassian API token for that account, classic or scoped. Encrypted before the job starts and never logged in plain text. The encrypted value stays in the job’s execution record for up to 90 days, where only the indexing pipeline can decrypt it. Plain ASCII, up to 2,048 characters.

confluence_emailstringRequired3-320 characters

Email of the Atlassian account that owns the API token. The job sees exactly what this account can see. Up to 320 characters.

confluence_sitestringRequired

The Confluence Cloud site, as a host (‘acme.atlassian.net’) or any URL on it (‘https://acme.atlassian.net/wiki/spaces/ENG’). Only *.atlassian.net sites are accepted. Confluence Data Center is not supported.

processing_typeenumRequired

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. ‘auto’ inspects each PDF and uses advanced only when it has photos, drawings, tables or scanned pages (logos and signatures do not count), otherwise basic; each file bills at the tier it used.

Allowed values:advancedbasicauto
space_keystringRequiredformat: "^~?[A-Za-z0-9._:-]{1,255}$"

Key of the Confluence space, as it appears in the space URL (/wiki/spaces/ENG has the key ‘ENG’).

custom_metadatamap from strings to strings or integers or doubles or booleans or lists of strings or nullOptional

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

forcebooleanOptionalDefaults to false

When true, every page and attachment in scope is re-indexed, including ones that have not changed since the last run. When false (default), unchanged pages are skipped and cost nothing.

include_attachmentsbooleanOptionalDefaults to true

When true, files attached to the pages are indexed as their own documents, up to 5,000 per job. Pictures, audio and video are left out unless include_images is true.

include_commentsbooleanOptionalDefaults to true

When true, footer and inline comments are added to each page’s text under a Comments heading.

include_imagesbooleanOptionalDefaults to false

Also import pictures, audio and video attached to pages. Default false. Requires include_attachments.

mask_piibooleanOptionalDefaults to false

When true, mask detected PII (emails, names, SSNs, etc.) in parsed text before embedding and storing.

pii_engineenum or nullOptional

Masking engine for this job. jev (default): TypeSafe’s hosted Jev classifier model; supports pii_fields and pii_instructions; there is no fallback engine, so a file Jev cannot mask fails to index. presidio: the legacy pattern engine, built-in categories only (rejects pii_fields and pii_instructions with 422), never a fallback. Requires mask_pii to be true. The earlier names captain-jev and captain-presidio keep working as before.

Allowed values:jevpresidiocaptain-jevcaptain-presidio
pii_fallbackboolean or object or nullOptional

Retry policy for jev, as {“retry_budget_seconds”: n}. There are no fallback engines. A non-empty engines list answers 422. On the multipart file upload endpoint, send it as a JSON string form field. With the earlier engine name captain-jev it is true (default, fall back to captain-presidio) or false (fail the file).

pii_fieldslist of objects or nullOptional

Additional PII categories to mask for this job, on top of the built-in set. Requires mask_pii to be true. Up to 20 fields. Each masked value is replaced with the field’s tag in angle brackets and appears in the masking report under the field’s name.

pii_instructionsstring or nullOptional<=1000 characters

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.

Response

Successful Response

job_idstring
statusstringOptionalDefaults to pending
custom_metadatamap from strings to any or nullOptional

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

Errors

POST/v2/collections/:collection_name/index/confluence/space
import requests

BASE_URL = "https://api.filesearch.dev"
API_KEY = "your_api_key"

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

response = requests.post(
    f"{BASE_URL}/v2/collections/my_documents/index/confluence/space",
    headers=headers,
    json={
        "confluence_site": "acme.atlassian.net",
        "confluence_email": "importer@acme.com",
        "confluence_api_token": "your_atlassian_api_token",
        "space_key": "ENG",
        "processing_type": "basic"
    },
    timeout=60.0
)

if response.status_code in [200, 201]:
    data = response.json()
    print(f"Job started! ID: {data['job_id']}")
else:
    print(f"Error: {response.status_code}")
200
{
  "job_id": "job_confluence_abc123",
  "status": "pending"
}
Was this page helpful?