Skip to main content

​
Namespaces

A namespace is a collection of documents that share a common schema. Namespaces isolate documents from each other; searches only run against a single namespace at a time.

​
Creating namespaces

Namespaces are created automatically the first time you upload documents to them. There is no separate creation step. 
# This creates the "support-tickets" namespace if it doesn't exist
curl -X POST https://api.withcharcoal.com/v1/namespaces/support-tickets/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"documents": [{"id": "1", "title": "Example"}]}'

​
Naming rules

Namespace names must:
  • Be 1 to 128 characters long
  • Contain only alphanumeric characters, hyphens (-), underscores (_), and dots (.)

​
Listing namespaces

curl https://api.withcharcoal.com/v1/namespaces \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "results": [
    {
      "id": 1,
      "name": "support-tickets",
      "company_id": 1,
      "company_name": "acme",
      "created_at": "2025-01-15T10:00:00.000Z",
      "updated_at": "2025-01-15T12:30:00.000Z",
      "attributes_schema": {
        "title": { "type": "string", "is_searchable": true },
        "body": { "type": "string", "is_searchable": true },
        "priority": { "type": "string", "is_filterable": true }
      }
    }
  ]
}

​
Documents

Documents are JSON objects stored in a namespace. Each document has a required id and arbitrary attributes that you define.

​
Document structure

Every document must have an id field. All other fields are user-defined attributes. 
{
  "id": "ticket-4521",
  "title": "Login page returns 500 error",
  "body": "Users report seeing a 500 error when attempting to log in via SSO...",
  "priority": "high",
  "created_at": "2025-03-10T14:22:00Z",
  "tags": ["auth", "sso", "production"]
}
The id must be a UUID or a string up to 64 characters. If you upload a document with an existing id, it replaces the previous version.

​
Uploading documents

Upload documents with a POST request. You can upload up to 10,000 documents per request. 
curl -X POST https://api.withcharcoal.com/v1/namespaces/my-namespace/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {"id": "1", "title": "First doc", "body": "..."},
      {"id": "2", "title": "Second doc", "body": "..."}
    ],
    "schema": {
      "title": {"type": "string", "is_searchable": true},
      "body": {"type": "string", "is_searchable": true}
    }
  }'

​
Deleting documents

Delete documents by ID: 
curl -X DELETE https://api.withcharcoal.com/v1/namespaces/my-namespace/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["doc-1", "doc-2"]}'
You can also delete by root document ID, which removes a document and all of its children: 
curl -X DELETE https://api.withcharcoal.com/v1/namespaces/my-namespace/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"root_document_ids": ["parent-doc-1"]}'

​
Retrieving a document

Fetch a single document by ID: 
curl https://api.withcharcoal.com/v1/namespaces/my-namespace/documents/doc-1 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Schema

Each namespace has an attributes schema that defines the type and indexing behavior of document attributes. See the Schema guide for the full reference.