Skip to main content
Charcoal search takes a natural language query and returns synthesized answers with cited findings from your documents. A search request requires two fields:
  • objective: a short sentence describing what you’re looking for
  • context: a more detailed description of your query, including any relevant background
curl -X POST https://api.withcharcoal.com/v1/namespaces/my-namespace/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Understand how authentication works",
    "context": "I need to implement SSO login for our app and want to know what authentication methods are supported, how tokens are managed, and any rate limits."
  }'

​
Response

{
  "session_id": "sess_abc123",
  "status": "completed",
  "documents_scanned": 150,
  "queries_executed": 4,
  "synthesis": "The platform supports three authentication methods: API keys, OAuth 2.0, and SAML-based SSO...",
  "results": [
    {
      "finding": "SSO is supported via SAML 2.0 with automatic user provisioning",
      "id": "doc-auth-sso",
      "excerpts": [
        "SAML 2.0 SSO can be configured in the admin panel. User accounts are automatically provisioned on first login."
      ]
    },
    {
      "finding": "Authentication tokens expire after 24 hours and can be refreshed",
      "id": "doc-auth-tokens",
      "excerpts": [
        "Access tokens are valid for 24 hours. Use the refresh token endpoint to obtain a new token without re-authenticating."
      ]
    }
  ]
}
FieldDescription
session_idUnique identifier for this search session.
statuscompleted or failed. Multi-turn searches may also return clarification_needed.
documents_scannedNumber of documents examined during the search.
queries_executedNumber of search queries run internally.
synthesisA natural language summary that answers your query, citing the results.
resultsArray of findings, each with a finding summary, source id, and relevant excerpts.
clarification_neededPresent when the search needs more information. See multi-turn search.

​
Streaming

Set stream: true to receive server-sent events with real-time progress updates. 
curl -X POST https://api.withcharcoal.com/v1/namespaces/my-namespace/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Understand how authentication works",
    "context": "What SSO methods are supported?",
    "stream": true
  }'
The stream emits the following event types:
EventDescription
statusProgress update with a message field (e.g., "Searching documents...")
session_resultFinal result object, same shape as the non-streaming response
errorError with a code field
event: status
data: {"message": "Searching documents..."}

event: status
data: {"message": "Analyzing 12 relevant documents..."}

event: session_result
data: {"session_id": "sess_abc123", "status": "completed", "synthesis": "...", "results": [...]}

​
Filters

Narrow search results using attribute filters. Only attributes marked as is_filterable in the namespace schema can be filtered on. 
curl -X POST https://api.withcharcoal.com/v1/namespaces/my-namespace/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Find critical bugs",
    "context": "Show me all critical severity bugs reported in the last month.",
    "filters": {
      "$and": [
        {"severity": "critical"},
        {"status": {"$in": ["open", "in_progress"]}}
      ]
    }
  }'
See the Filters guide for the full filter syntax.

​
Including document attributes

Set include_attributes: true to include the full document attributes in each result: 
{
  "objective": "Find critical bugs",
  "context": "...",
  "include_attributes": true
}
Each result will include an attributes object containing all of the source document’s fields. Set multiturn: true to enable multi-turn mode. When Charcoal needs more information to answer your query, the response will have status: "clarification_needed" with a question and optional suggested answers. 
{
  "session_id": "sess_abc123",
  "status": "clarification_needed",
  "clarification_needed": {
    "question": "Are you looking for SSO configuration for the admin panel or the end-user application?",
    "options": ["Admin panel", "End-user application", "Both"]
  }
}
Respond by sending a continuation request to the session’s URL with your answer: 
curl -X POST https://api.withcharcoal.com/v1/namespaces/my-namespace/search/sess_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "End-user application"
  }'
The search continues and returns results as usual.