Chat API

Base URL: https://api.samsar.one/v1
External managed-inference base URL: https://api.samsar.one/v2/external
Auth: Authorization: Bearer <API_KEY>
Pricing:
- /chat/enhance: 30 credits per request.
- /v2/external/chat and /v2/external/chat/completions are usage-based external inference endpoints. Text and vision inputs use the selected adapter token rates shown below.
- /v2/external/moderation and /v2/external/moderations: no credit charge.
- Embedding routes are usage-based. Credits scale with the amount of text processed and use the standard 100 credits = $1 conversion.
- URL embedding routes add crawl cost before credit conversion and apply a 2.5x ingestion multiplier because they include both crawling and embedding work.
- /chat/generate_embeddings_from_plain_text applies a 2.5x multiplier to embedding-token cost only. It does not add crawl charges.
- /chat/delete_embedding and /chat/delete_embeddings: no token charges.
/chat/enhance and embedding routes are synchronous. External chat defaults to synchronous execution and also supports durable queued requests with status polling.

POST /chat/enhance

Improve a message while keeping its intent. metadata is optional contextual data that influences the rewrite. Provide language (ISO 639-1 code or language name) if you want the output in a specific language; otherwise detection is automatic.

Request body

{
  "message": "Draft caption text",
  "metadata": {
    "audience": "gen z",
    "tone": "playful"
  },
  "language": "FR"
}

message required, non-empty string.
metadata optional object.
language optional string, ISO 639-1 code (e.g., EN, FR, TH) or language name; defaults to auto-detect.

Sample request

curl -X POST https://api.samsar.one/v1/chat/enhance \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "launching soon, stay tuned!",
    "metadata": { "channel": "instagram" },
    "language": "FR"
  }'

Success response (200)

{
  "content": "We’re launching soon—follow along for first looks and drop reminders!"
}

Common errors

400 missing or empty message.
401 invalid API key.
402 insufficient credits.

POST /v2/external/chat/completions

Create an OpenAI-compatible chat completion billed through Samsar credits. Use this endpoint when an external deployment or integration needs managed inference without supplying native OpenAI or Google credentials. The same handler is available at /v2/external/chat, /v2/external/assistant, and /v2/external/assistant/completions; /api/v2/external/* is also supported.

This endpoint is synchronous by default. For durable submission, idempotent retries, request correlation, and polling, see External assistant and chat completions.

Pricing

Adapter	Context	Input credits / 1M tokens	Cached input credits / 1M tokens	Output credits / 1M tokens
`gpt-5.5`	Up to 272k input tokens	625	62.5	3,750
`gpt-5.5`	Above 272k input tokens	1,250	125	5,625
`gemini-3.1-pro`	Up to 200k input tokens	250	25	1,500
`gemini-3.1-pro`	Above 200k input tokens	500	50	2,250

Vision requests use the same adapter token rates for image-derived input tokens and generated output tokens. Responses include x-credits-charged and x-credits-remaining headers when credits are deducted.

Request body

{
  "model": "gpt-5.5",
  "messages": [
    { "role": "developer", "content": "Return concise JSON." },
    { "role": "user", "content": "Create a three-scene outline for a launch video." }
  ],
  "response_format": { "type": "json_object" }
}

For vision, send OpenAI-compatible image message parts:

{
  "model": "gemini-3.1-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this image for a video prompt." },
        { "type": "image_url", "image_url": { "url": "https://example.com/frame.png" } }
      ]
    }
  ]
}

Sample request

curl -X POST https://api.samsar.one/v2/external/chat/completions \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "Write one cinematic product video theme." }
    ]
  }'

Success response (200)

The response is an OpenAI-compatible chat completion object.

Queued mode instead returns HTTP 202 with request_id, status, and poll_url. The default server execution timeout is 10 minutes; polling avoids holding the HTTP connection for that entire period.

Common errors

400 missing or invalid messages.
401 invalid API key.
402 insufficient credits.

POST /v2/external/moderation

Create an OpenAI-compatible moderation check for external deployments. The same handler is available at /external/moderations, /v2/external/moderation, and /v2/external/moderations.

This route requires a Samsar API key but does not charge credits.

Request body

{
  "input": "A user prompt or generated draft to moderate.",
  "model": "omni-moderation-latest"
}

Sample request

curl -X POST https://api.samsar.one/v2/external/moderation \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Create a family-safe product launch video."
  }'

Success response (200)

The response includes the OpenAI-compatible moderation result plus a decision object with the normalized Samsar pass/fail decision.

Common errors

400 missing or invalid input.
401 invalid API key.
500 moderation provider is not configured.

POST /chat/create_embedding

Create a new embedding template from either a JSON array or a URL list. JSON records are embedded directly. URL inputs are first crawled with Firecrawl, minimally cleaned, normalized into the same compatible record structure, and then embedded using text-embedding-3-large.

Request body

{
  "name": "listings",
  "records": [
    {
      "id": "A1",
      "city": "Austin",
      "price": 1800,
      "duration": 12,
      "description": "Modern 1BR close to downtown."
    }
  ]
}

records required when embedding JSON input.
urls or url can be used instead of records to build embeddings from crawled web pages.
name optional string. Also accepted: embedding_name, template_name.
Each record should include an id, _id, or equivalent identifier. If missing, the API generates one per record.
field_options optional map (or array) of per-field flags:
- searchable: false excludes the field (and nested paths) from embedding input.
- filterable: true includes the field in structured filters used for search/similar queries.
- filterable: false excludes the field from structured filters.
- retrievable: false removes the field from raw record payloads in search results.
- Use dot notation (e.g. owner.email) for nested fields.

You can also inline flags in records using a { value, searchable, filterable, retrievable } wrapper.

{
  "records": [
    {
      "id": "A1",
      "internal_notes": { "value": "private note", "searchable": false, "retrievable": false }
    }
  ]
}

URL request body

{
  "name": "product-docs",
  "urls": [
    "https://example.com/docs/getting-started",
    "https://example.com/docs/pricing"
  ]
}

URL mode crawls each URL with Firecrawl before embedding.
Optional levels controls crawl depth for URL mode. It can be passed as a query param or body field.
- 1: crawl only the listed seed URLs.
- 2: crawl each seed URL plus URLs linked directly from it.
- 3: crawl each seed URL plus two link hops outward.
- Default: 2. Maximum: 3.
URL mode is capped at 50 total crawled pages per request across all seed URLs.
Returned embeddings remain compatible with /chat/search_against_embedding and /chat/similar_to_embedding.
URL mode responses may include input_url_count, processed_url_count, firecrawl_credits_used, skipped_urls, and crawl_errors.

Sample request

curl -X POST "https://api.samsar.one/v1/chat/create_embedding?levels=2" \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "listings",
    "field_options": {
      "description": { "searchable": true },
      "internal_notes": { "searchable": false, "retrievable": false },
      "price": { "filterable": true }
    },
    "records": [
      { "id": "A1", "city": "Austin", "price": 1800, "description": "Modern 1BR close to downtown." },
      { "id": "A2", "city": "Dallas", "price": 2200, "description": "Spacious 2BR with a balcony." }
    ]
  }'

Success response (200)

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "template_hash": "b0e6f2d2c2f1d0c4d9f7f3a1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9",
  "hash_link": "embedding_template:b0e6f2d2c2f1d0c4d9f7f3a1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9",
  "record_count": 2,
  "structured_fields": [
    { "key": "city", "type": "string" },
    { "key": "price", "type": "number" }
  ],
  "unstructured_fields": ["description"]
}

Common errors

400 missing records and urls, or invalid URL input.
401 invalid API key.
402 insufficient credits.

POST /chat/create_embedding_from_url

Create a new embedding template from one URL or a URL list. This is the explicit URL-only variant of /chat/create_embedding and uses the same Firecrawl-backed ingestion flow.

Request body

{
  "name": "product-docs",
  "urls": [
    "https://example.com/docs/getting-started",
    "https://example.com/docs/pricing"
  ]
}

urls required array of URL strings. url is also accepted for a single URL.
Optional levels controls crawl depth for URL mode. It can be sent as a query param or body field.
- 1: crawl only the listed seed URLs.
- 2: crawl each seed URL plus URLs linked directly from it.
- 3: crawl each seed URL plus two link hops outward.
- Default: 2. Maximum: 3.
URL mode is capped at 50 total crawled pages per request across all seed URLs.
field_options is optional and follows the same rules as /chat/create_embedding.
Samsar crawls the URLs, minimally cleans the extracted text, stores normalized URL metadata, and creates embeddings in the same query-compatible format as JSON-record embeddings.
Billing applies Firecrawl crawl usage at a 2.5x multiplier based on actual pages crawled, then applies the embedding token cost with its own 2.5x multiplier.

Sample request

curl -X POST "https://api.samsar.one/v1/chat/create_embedding_from_url?levels=2" \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-docs",
    "urls": [
      "https://example.com/docs/getting-started",
      "https://example.com/docs/pricing"
    ]
  }'

Success response (200)

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "template_hash": "b0e6f2d2c2f1d0c4d9f7f3a1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9",
  "hash_link": "embedding_template:b0e6f2d2c2f1d0c4d9f7f3a1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9",
  "record_count": 2,
  "input_url_count": 2,
  "processed_url_count": 12,
  "firecrawl_credits_used": 12,
  "crawl_levels": 2,
  "max_links": 50,
  "structured_fields": [
    { "key": "hostname", "type": "string" },
    { "key": "status_code", "type": "number" }
  ],
  "unstructured_fields": ["title", "description", "content"]
}

Common errors

400 missing or invalid urls.
401 invalid API key.
402 insufficient credits.
422 URLs crawled successfully but produced no extractable content.
5xx Firecrawl crawl failure or upstream processing failure.

POST /chat/generate_embeddings_from_plain_text

Create a new embedding template from already cleaned plain text input. This route is the embedding-only stage of the URL ingestion flow: you provide the cleaned text directly, Samsar skips crawling, and it stores the result in the same query-compatible embedding format used by the JSON and URL endpoints.

Request body

{
  "name": "product-docs-clean",
  "plain_text": [
    {
      "url": "https://example.com/docs/getting-started",
      "title": "Getting Started",
      "content": "Cleaned plain text content from the page."
    }
  ]
}

plain_text required. Accepted shapes:
- a single string
- a single object
- an array of strings or objects
For object entries, the cleaned text can be provided in plain_text, content, text, cleaned_text, markdown, or body.
Optional object fields such as url, title, description, and language are preserved and normalized into the stored record when present.
field_options is optional and follows the same rules as /chat/create_embedding.
Pricing uses the embedding token cost with a 2.5x multiplier and does not charge any crawl credits.

Sample request

curl -X POST https://api.samsar.one/v1/chat/generate_embeddings_from_plain_text \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-docs-clean",
    "plain_text": [
      {
        "url": "https://example.com/docs/getting-started",
        "title": "Getting Started",
        "content": "Cleaned plain text content from the page."
      },
      {
        "url": "https://example.com/docs/pricing",
        "title": "Pricing",
        "content": "Cleaned pricing page text."
      }
    ]
  }'

Success response (200)

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "template_hash": "b0e6f2d2c2f1d0c4d9f7f3a1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9",
  "hash_link": "embedding_template:b0e6f2d2c2f1d0c4d9f7f3a1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9",
  "record_count": 2,
  "structured_fields": [
    { "key": "hostname", "type": "string" }
  ],
  "unstructured_fields": ["title", "content"]
}

Common errors

400 missing or invalid plain_text.
401 invalid API key.
402 insufficient credits.

POST /chat/update_embedding

Append or update records for an existing template. New records are embedded and merged into the template schema; matching sourceId records are upserted.

Request body

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "field_options": {
    "description": { "searchable": true },
    "internal_notes": { "searchable": false, "retrievable": false },
    "price": { "filterable": true }
  },
  "records": [
    {
      "id": "A3",
      "city": "Houston",
      "price": 2000,
      "description": "Bright 2BR near the park."
    }
  ]
}

field_options follows the same rules as /chat/create_embedding. If omitted, the template's existing field options are reused.

Success response (200)

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "template_hash": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1908",
  "record_count": 3,
  "structured_fields": [
    { "key": "city", "type": "string" },
    { "key": "price", "type": "number" }
  ],
  "unstructured_fields": ["description"]
}

Common errors

400 missing template_id or records.
401 invalid API key.
402 insufficient credits.
404 template not found.

POST /chat/delete_embeddings

Delete all embeddings for a template. The template remains, but its record count becomes 0.

Request body

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3"
}

Success response (200)

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "deleted_count": 250,
  "record_count": 0,
  "status": "empty"
}

Common errors

400 missing template_id.
401 invalid API key.
404 template not found.

POST /chat/delete_embedding

Delete one or more embeddings from a template by record id. Use the id returned in search results or the id you supplied in the original records.

Request body

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "source_id": "A2"
}

source_id optional string. Also accepted: sourceId, id, record_id.
source_ids optional array of strings. Also accepted: sourceIds, ids, record_ids.
Provide either source_id or source_ids.

Success response (200)

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "deleted_count": 1,
  "record_count": 249,
  "status": "ready"
}

Common errors

400 missing template_id or source_id/source_ids.
401 invalid API key.
404 template not found.

POST /chat/search_against_embedding

Search within a template using a natural language query. The API extracts structured filters first, then performs vector similarity. Optional rerank can re-order top results.

Request body

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "search_term": "2 bedroom apartment in Dallas under 2500",
  "search_params": { "city": "Dallas", "price": { "max": 2500 } },
  "limit": 10,
  "num_candidates": 50,
  "rerank": true,
  "include_raw": true
}

Success response (200)

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "template_name": "listings",
  "structured_filters": { "city": "Dallas", "price": 2500 },
  "results": [
    {
      "id": "A2",
      "score": 0.92,
      "structured_filters": { "city": "Dallas", "price": 2200 },
      "record": {
        "id": "A2",
        "city": "Dallas",
        "price": 2200,
        "description": "Spacious 2BR with a balcony."
      }
    }
  ]
}

Optional structured_filters (or filters) can be supplied to force filters.
Optional search_params (or searchParams) supplies a filter payload validated against the template schema and applied before vector search. structured_filters overrides overlapping keys.
Use include_raw: false to omit the original record payloads.

Common errors

400 missing template_id or search_term.
401 invalid API key.
402 insufficient credits.
404 template not found.

POST /chat/similar_to_embedding

Return similar results for a query within a template (vector similarity only). You can pass a natural language search_term or a JSON payload in search_json which is converted into the template's search document before embedding.

Request body

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "search_term": "modern downtown apartment",
  "search_params": { "city": "Austin" },
  "limit": 10,
  "min_results": 10
}

Request body (JSON search)

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "search_json": {
    "city": "Austin",
    "price": 2000,
    "description": "modern downtown apartment"
  },
  "limit": 10
}

Provide search_term or search_json.
Optional search_params (or searchParams) prefilters by structured fields (validated against the template schema) before vector similarity.
Optional min_results ensures at least that many results are requested (may still return fewer if the template has fewer matches).

Success response (200)

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "structured_filters": {},
  "matches": [
    { "id": "A1", "score": 0.88 },
    { "id": "A2", "score": 0.73 }
  ]
}

Common errors

400 missing template_id or search_term/search_json.
401 invalid API key.
402 insufficient credits.
404 template not found.

GET /chat/embedding_templates

List embedding templates available for the API key.

Query params

limit optional integer (default 50, max 100).
offset optional integer (default 0).

Sample request

curl -X GET "https://api.samsar.one/v1/chat/embedding_templates?limit=25&offset=0" \
  -H "Authorization: Bearer $SAMSAR_API_KEY"

Success response (200)

{
  "templates": [
    {
      "template_id": "66f3b0d64c8bca9c6f2bd1a3",
      "name": "listings",
      "template_hash": "b0e6f2d2c2f1d0c4d9f7f3a1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9",
      "hash_link": "embedding_template:b0e6f2d2c2f1d0c4d9f7f3a1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9",
      "record_count": 3,
      "structured_fields": [
        { "key": "city", "type": "string" },
        { "key": "price", "type": "number" }
      ],
      "unstructured_fields": ["description"],
      "embedding_model": "text-embedding-3-large",
      "created_at": "2024-11-03T12:00:00.000Z",
      "updated_at": "2024-11-03T12:10:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

Common errors

401 invalid API key.

GET /chat/embedding_status

Check whether embeddings exist for a template id.

Query params

template_id required string.

Sample request

curl -X GET "https://api.samsar.one/v1/chat/embedding_status?template_id=66f3b0d64c8bca9c6f2bd1a3" \
  -H "Authorization: Bearer $SAMSAR_API_KEY"

Success response (200)

{
  "template_id": "66f3b0d64c8bca9c6f2bd1a3",
  "has_embeddings": true,
  "record_count": 3,
  "status": "ready"
}

Common errors

400 missing template_id.
401 invalid API key.
404 template not found.

POST /chat/enhance​

POST /v2/external/chat/completions​

POST /v2/external/moderation​

POST /chat/create_embedding​

POST /chat/create_embedding_from_url​

POST /chat/generate_embeddings_from_plain_text​

POST /chat/update_embedding​

POST /chat/delete_embeddings​

POST /chat/delete_embedding​

POST /chat/search_against_embedding​

POST /chat/similar_to_embedding​

GET /chat/embedding_templates​

GET /chat/embedding_status​

POST /chat/enhance

POST /v2/external/chat/completions

POST /v2/external/moderation

POST /chat/create_embedding

POST /chat/create_embedding_from_url

POST /chat/generate_embeddings_from_plain_text

POST /chat/update_embedding

POST /chat/delete_embeddings

POST /chat/delete_embedding

POST /chat/search_against_embedding

POST /chat/similar_to_embedding

GET /chat/embedding_templates

GET /chat/embedding_status