ContentIQ Documentation
API Reference

REST endpoints for ingestion, storage administration, and analytics.

API Reference

Explore REST endpoints for ingestion, storage administration, and analytics.

Getting Your API Key

Through the Web Interface

  1. Login to your ContentIQ account
  2. Go to Settings (left sidebar)
  3. Click the ContentIQ API tab
  4. Click Generate next to ContentIQ API Key
  5. Copy the key — you'll only see it once!

Important

  • Keep your API key secure. Don't share it or commit it to code repositories.
  • Each time you generate a new key, the previous one becomes invalid.
  • You must be logged into your ContentIQ account to generate keys.

Rate Limits

API requests are rate-limited per user per minute. Limits vary by plan. Exceeding the limit returns an HTTP 429 (Too Many Requests) response.

Limits by plan

  • Starter: 50 requests per minute
  • Essentials: 100 requests per minute
  • Standard: 150 requests per minute
  • Premium: 200 requests per minute

Headless Chat

Notes:

  • Agent ID is the watsonx Orchestrate Agent ID (find via ADK or in the ContentIQ dashboard under Usage Analytics).
  • Authentication uses Authorization: Bearer YOUR_API_KEY_HERE.
  • Thread ID should be generated per conversation and reused to preserve context.

Endpoint: POST /api/headless/chat

curl -X POST "https://backend.contentiq.symplistic.ai/api/headless/chat" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE" \
        -d '{
          "agent_id": "your-agent-id",
          "message": "Hello! What can you help me with?",
          "thread_id": "my-conversation-123"
        }'

Streaming Chat

Server-Sent Events (SSE) variant for real-time streaming responses.

Endpoint: POST /api/headless/chat/stream

curl -N -X POST "https://backend.contentiq.symplistic.ai/api/headless/chat/stream" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE" \
        -d '{
          "agent_id": "your-agent-id",
          "message": "Stream the answer please",
          "thread_id": "my-conversation-123"
        }'

Conversation History

Fetch or clear a stored headless conversation thread.

Endpoints:

  • GET /api/headless/conversations/<agent_id>/<thread_id>
  • DELETE /api/headless/conversations/<agent_id>/<thread_id>
curl -X GET "https://backend.contentiq.symplistic.ai/api/headless/conversations/your-agent-id/my-conversation-123" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE"

Document Ingestion

Upload local documents into an agent knowledge base.

Endpoints:

  • POST /api/headless/document/ingest
  • GET /api/headless/document/status/<run_id>/stream
curl -X POST "https://backend.contentiq.symplistic.ai/api/headless/document/ingest" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE" \
        -F "[email protected]" \
        -F "[email protected]" \
        -F "agent_id=your-agent-id" \
        -F "agent_name=My Agent"
curl -N -H "Authorization: Bearer YOUR_API_KEY_HERE" \
        "https://backend.contentiq.symplistic.ai/api/headless/document/status/<YOUR_RUN_ID>/stream"

Website Ingestion

Start a headless website crawl and stream its status.

Endpoints:

  • POST /api/headless/website/ingest
  • GET /api/headless/website/status/<run_id>/stream
curl -X POST "https://backend.contentiq.symplistic.ai/api/headless/website/ingest" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE" \
        -d '{
          "website_url": "https://www.example.com",
          "agent_id": "your-agent-id",
          "agent_name": "My Agent"
        }'

OneDrive

List OneDrive files, start ingestion, and monitor run status.

Endpoints:

  • GET /api/headless/onedrive/list-files
  • POST /api/headless/onedrive/ingest
  • GET /api/headless/onedrive/status/<run_id>
  • GET /api/headless/onedrive/status/<run_id>/stream
curl -X GET "https://backend.contentiq.symplistic.ai/api/headless/onedrive/list-files" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE"

SharePoint

Browse SharePoint sites and ingest site content.

Endpoints:

  • GET /api/headless/sharepoint/sites
  • GET /api/headless/sharepoint/sites/<site_id>/drives
  • GET /api/headless/sharepoint/sites/<site_id>/pages
  • GET /api/headless/sharepoint/sites/<site_id>/lists
  • POST /api/headless/sharepoint/ingest
  • GET /api/headless/sharepoint/status/<run_id>
  • GET /api/headless/sharepoint/status/<run_id>/stream
curl -X GET "https://backend.contentiq.symplistic.ai/api/headless/sharepoint/sites" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE"

Box

List Box files and start Box ingestion.

Endpoints:

  • GET /api/headless/box/list-files
  • POST /api/headless/box/ingest
curl -X GET "https://backend.contentiq.symplistic.ai/api/headless/box/list-files" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE"

IBM COS

List IBM Cloud Object Storage objects and start ingestion.

Endpoints:

  • GET /api/headless/ibm_cos/list-files
  • POST /api/headless/ibm_cos/ingest
curl -X GET "https://backend.contentiq.symplistic.ai/api/headless/ibm_cos/list-files?prefix=folder/" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE"

Scheduled Ingestion (Headless)

Configure and run recurring ingestion without the ContentIQ UI. These endpoints mirror the session scheduler API (/api/scheduler/*) but use your headless API key instead of a browser session.

Notes:

  • Authentication: Authorization: Bearer YOUR_API_KEY_HERE — the service account is inferred from the key; request bodies do not need a username field.
  • Sources: website, onedrive, sharepoint, googledrive, and box. The document source is not supported for scheduled trigger (returns 501).
  • Plan limits: the number of scheduled configs per account depends on your plan (Starter: 5, Essentials: 5, Standard: 5, Premium: 10).
  • Status streaming: trigger responses include a status_stream_endpoint for website, OneDrive, and SharePoint runs. Box and Google Drive do not expose a headless status stream yet.

Endpoints:

  • GET /api/headless/scheduler/config — list all configs (optional ?agent_id=<uuid> for one config)
  • GET /api/headless/scheduler/agent-availability?agent_id=<uuid> — check whether an agent can be scheduled
  • POST /api/headless/scheduler/config — create or update a schedule
  • DELETE /api/headless/scheduler/config — delete one config (agent_id) or all configs
  • POST /api/headless/scheduler/trigger — run a scheduled ingest now
curl -X GET "https://backend.contentiq.symplistic.ai/api/headless/scheduler/config" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE"
curl -X GET "https://backend.contentiq.symplistic.ai/api/headless/scheduler/config?agent_id=550e8400-e29b-41d4-a716-446655440000" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE"

Save Schedule Config

Create or update a scheduled ingest for an agent. Each agent can have at most one schedule. The same JSON body as POST /api/scheduler/config applies, without username.

Endpoint: POST /api/headless/scheduler/config

Required fields

  • agent_id — UUID of the agent to ingest for
  • frequency — daily, every_x_days, weekly, or monthly
  • source — website, onedrive, sharepoint, googledrive, or box
  • run_time — 24-hour format HH:MM (e.g. 09:00, 09:37)
  • timezone — IANA time zone (e.g. UTC, America/New_York)

Source-specific fields

  • website: website_url (required). Ingest behaviour is always full re-ingest.
  • onedrive / googledrive: selected_folders array or legacy folder_id (required).
  • sharepoint: site_id (required); plus selected_folders, selected_drives, or ingest_entire_site: true.
  • box: selected_items array or legacy folder_id (required).

Optional fields

  • agent_name — display label (UI only)
  • ingest_behaviour — full_reingest, changed_only, new_only, or changed_and_new (connector sources only; default full_reingest)
  • frequency_days — required when frequency is every_x_days (2–90)
  • weekly_day — required when frequency is weekly (0=Sunday … 6=Saturday)
  • monthly_day — required when frequency is monthly (1–28)
  • current_agent_id — when editing an existing config for a different agent

Example — daily website re-ingest:

curl -X POST "https://backend.contentiq.symplistic.ai/api/headless/scheduler/config" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE" \
        -d '{
          "agent_id": "550e8400-e29b-41d4-a716-446655440000",
          "agent_name": "My Agent",
          "frequency": "daily",
          "source": "website",
          "run_time": "09:00",
          "timezone": "America/New_York",
          "website_url": "https://www.example.com"
        }'

Example — weekly OneDrive ingest with changed-and-new behaviour:

curl -X POST "https://backend.contentiq.symplistic.ai/api/headless/scheduler/config" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE" \
        -d '{
          "agent_id": "550e8400-e29b-41d4-a716-446655440000",
          "frequency": "weekly",
          "weekly_day": 1,
          "source": "onedrive",
          "ingest_behaviour": "changed_and_new",
          "run_time": "09:00",
          "timezone": "UTC",
          "selected_folders": [
            {"id": "01ABC123XYZ", "name": "Documents"}
          ]
        }'

Delete a config:

curl -X DELETE "https://backend.contentiq.symplistic.ai/api/headless/scheduler/config" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE" \
        -d '{"agent_id": "550e8400-e29b-41d4-a716-446655440000"}'

Trigger Scheduled Run

Run a scheduled ingest immediately — useful for cron jobs, CI pipelines, or external schedulers. Loads the saved config and starts ingestion using the same internal paths as the UI “Run Now” button.

Endpoint: POST /api/headless/scheduler/trigger

Provide agent_id to trigger one agent, or send an empty body {} to trigger all configs for the account.

curl -X POST "https://backend.contentiq.symplistic.ai/api/headless/scheduler/trigger" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE" \
        -d '{
          "agent_id": "550e8400-e29b-41d4-a716-446655440000"
        }'
curl -X POST "https://backend.contentiq.symplistic.ai/api/headless/scheduler/trigger" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_API_KEY_HERE" \
        -d '{}'

Success response (202):

{
          "ok": true,
          "message": "Ingestion started",
          "ingestion_run_id": "d610a70d-293a-4e78-bd48-15b4d4b10446",
          "source": "website",
          "status_stream_endpoint": "/api/headless/website/status/d610a70d-293a-4e78-bd48-15b4d4b10446/stream"
        }

Stream run progress (SSE):

curl -N -H "Authorization: Bearer YOUR_API_KEY_HERE" \
        "https://backend.contentiq.symplistic.ai/api/headless/website/status/<YOUR_RUN_ID>/stream"

Common errors

  • 404 — no scheduler config found for the agent or account
  • 409 — ingest already running for that agent (active_ingestion_run_id in response)
  • 501 — document source is not supported for scheduled trigger

List Structured Data Files (Headless)

Returns structured files for an agent. Supports search, optional pagination, and optional detailed schema metadata.

curl -X GET "https://backend.contentiq.symplistic.ai/api/headless/structured_data/files?agent_id={agent_id}" \
          -H "Authorization: Bearer YOUR_API_KEY_HERE"
curl -X GET "https://backend.contentiq.symplistic.ai/api/headless/structured_data/files?agent_id={agent_id}&limit=50&offset=0&detailed=true" \
          -H "Authorization: Bearer YOUR_API_KEY_HERE"

Delete Structured Data File (Headless)

Remove a structured data file by filename.

curl -X DELETE "https://backend.contentiq.symplistic.ai/api/headless/structured_data/files/{filename}?agent_id={agent_id}" \
          -H "Authorization: Bearer YOUR_API_KEY_HERE"

List Milvus Sources (Headless)

List distinct sources in an agent vector collection.

Endpoint: GET /api/headless/milvus/sources?agent_id=...

curl -X GET "https://backend.contentiq.symplistic.ai/api/headless/milvus/sources?agent_id={agent_id}&batch_size=512" \
          -H "Authorization: Bearer YOUR_API_KEY_HERE"

Delete Milvus Chunks by Source (Headless)

Delete all chunks for a specific source URL.

Endpoint: DELETE /api/headless/milvus/chunks

curl -X DELETE "https://backend.contentiq.symplistic.ai/api/headless/milvus/chunks" \
          -H "Authorization: Bearer YOUR_API_KEY_HERE" \
          -H "Content-Type: application/json" \
          -d '{
            "agent_id": "{agent_id}",
            "source": "https://example.com/document1.pdf"
          }'

Delete Entire Milvus Collection (Headless)

⚠️ WARNING: This permanently deletes the entire Milvus collection for an agent. This action cannot be undone.

Endpoint: DELETE /api/headless/milvus/collection

curl -X DELETE "https://backend.contentiq.symplistic.ai/api/headless/milvus/collection" \
          -H "Authorization: Bearer YOUR_API_KEY_HERE" \
          -H "Content-Type: application/json" \
          -d '{
            "agent_id": "{agent_id}"
          }'

Milvus Credentials (Headless)

Manage service-account-scoped Milvus credentials used by headless vector operations.

Endpoints:

  • GET /api/headless/milvus/credentials
  • POST /api/headless/milvus/credentials
  • DELETE /api/headless/milvus/credentials
curl -X POST "https://backend.contentiq.symplistic.ai/api/headless/milvus/credentials" \
          -H "Authorization: Bearer YOUR_API_KEY_HERE" \
          -H "Content-Type: application/json" \
          -d '{
            "uri": "https://your-milvus-endpoint",
            "token": "your-milvus-token"
          }'