Skip to main content
POST
/
v1
/
namespaces
/
{namespace}
/
search
JavaScript
import Charcoal from '@charcoalhq/sdk';

const client = new Charcoal({
  apiKey: process.env['CHARCOAL_API_KEY'], // This is the default and can be omitted
});

const searchResponse = await client.namespaces.search.create('namespace', {
  context: 'context',
  objective: 'objective',
});

console.log(searchResponse.session_id);
{
  "session_id": "<string>",
  "status": "completed",
  "synthesis": "<string>",
  "results": [
    {
      "finding": "<string>",
      "id": "<string>",
      "excerpts": [
        "<string>"
      ],
      "attributes": {}
    }
  ],
  "documents_scanned": 123,
  "queries_executed": 123,
  "clarification_needed": {
    "question": "<string>",
    "options": [
      "<string>"
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
namespace
string
required

Namespace identifier. Alphanumeric characters, hyphens, underscores, and dots. Max 128 characters.

Maximum string length: 128
Pattern: ^[A-Za-z0-9-_.]{1,128}$

Body

application/json
​
objective
string
required

One sentence describing what you are looking for.

​
context
string
required

Additional context that helps the search system understand your intent. For example, relevant terminology, constraints, or prior knowledge.

​
filters
And Condition · object

Recursive filter object. One of: { $and: [Filter, ...] } (all must match), { $or: [Filter, ...] } (any must match), or { field_name: FieldCondition } (field-level condition).

​
stream
boolean
default:false

Whether to stream the response as server-sent events.

​
include_attributes
boolean
default:false

Whether to include document attributes in search results.

​
multiturn
boolean
default:false

Enable multi-turn mode. When true, the response includes a session_id and may return clarification_needed status. When false (default), the search always completes in a single request.

Response

Successful response. When stream is false (default), returns JSON. When stream is true, returns text/event-stream.

​
session_id
string
required

Unique identifier for this search session.

​
status
enum<string>
required
Available options:
completed,
clarification_needed,
failed
​
synthesis
string
required

Synthesized summary of all findings.

​
results
object[]
required
​
documents_scanned
integer

Number of documents scanned during the search.

​
queries_executed
integer

Number of queries executed during the search.

​
clarification_needed
object

Present when status is clarification_needed.