Alchemyst AI - AI-Native Context Management Platform

POST /api/v1/context/search/chat/completions OpenAI-compatible chat completions endpoint that grounds answers in the caller’s private Alchemyst context. It works as a drop-in replacement for /v1/chat/completions from the OpenAI SDK. The default model is Big Bull Alpha, an Alchemyst model. You can also pass any OpenRouter provider/model id and bring your own key. OpenRouter is an implementation detail of the endpoint, not a separate product surface.

Authentication

The endpoint supports two modes:

Mode	Authorization	LLM key	Use case
Alchemyst account	`Authorization: Bearer <ALCHEMYST_API_KEY>`	`llm_api_key`, `api_key`, or `x-llm-api-key`	Existing Alchemyst users
OpenRouter only	`Authorization: Bearer sk-or-...`	Same key, or `llm_api_key` / `x-llm-api-key`	Try the model without an Alchemyst account

OpenRouter-only callers must send a valid email on their first request. If an Alchemyst account already exists for that email, the request is rejected and the caller must authenticate with their Alchemyst API key instead. Later requests are identified by the OpenRouter key and do not need the email again. OpenRouter-only mode only supports an OpenRouter base_url.

Request

Query parameters

Parameter	Type	Default	Description
`mode`	`fast` \| `standard`	`standard`	`fast` prioritizes latency; `standard` performs a more complete search.
`context`	boolean	`false`	When `true`, include the joined grounding context in the response.

Body

Field	Type	Required	Description
`messages`	array	Yes	OpenAI-format messages. Must be non-empty.
`model`	string	No	Model name or OpenRouter id. Defaults to `Big Bull Alpha`.
`stream`	boolean	No	Stream the upstream SSE response. Defaults to `false`.
`api_key` / `apiKey` / `llm_api_key`	string	No	Provider LLM key. Can also be sent as `x-llm-api-key`.
`base_url` / `baseURL`	string	No	OpenAI-compatible base URL. Defaults to `https://openrouter.ai/api/v1`.
`email`	string	Conditional	Required on the first OpenRouter-only request.
`session_id`	string	No	Groups saved memory for this conversation.
`context_config`	object	No	Context search overrides. See below.
`similarity_threshold`	number	`0.3`	Top-level alias for `context_config.similarity_threshold`.
`minimum_similarity_threshold`	number	`0.2`	Top-level alias for `context_config.minimum_similarity_threshold`.
`scope`	`internal` \| `external`	`internal`	Top-level alias for `context_config.scope`.
`body_metadata`	object	No	Top-level alias for `context_config.body_metadata`.
`steering_prompt`	string	No	Extra instructions prepended to the internal tool guidance.
`magic_key`	string	No	Magic-key scope for shared context.

context_config accepts the same fields and takes precedence over the top-level aliases. It is sent inside the request body, next to messages and model:

{
  "model": "Big Bull Alpha",
  "messages": [
    { "role": "user", "content": "What did we decide about pricing?" }
  ],
  "context_config": {
    "similarity_threshold": 0.3,
    "minimum_similarity_threshold": 0.2,
    "scope": "internal",
    "body_metadata": {
      "fileName": "pricing_notes.txt",
      "groupName": ["pricing"],
      "lastModifiedAt": "2025-01-10T12:34:56.000Z",
      "modalities": ["text"]
    },
    "steering_prompt": "",
    "magic_key": null
  }
}

body_metadata holds metadata filters for the underlying context search. Recognized keys:

Key	Type	Description
`fileName`	string	Filter contexts by file name.
`groupName`	array of strings	Group names to filter contexts by. Defaults to `["default"]`.
`lastModifiedAt`	string (date-time)	Filter contexts by last modified timestamp.
`modalities`	array of `text` \| `image`	Modalities to search across.

Extra keys are allowed. When body_metadata is present without groupName, the search defaults to the default group.

If you are calling without an Alchemyst API key (OpenRouter-only mode), keep body_metadata empty — "body_metadata": {} — since there is no Alchemyst context to filter.

similarity_threshold must be greater than or equal to minimum_similarity_threshold.query is deprecated. Retrieval queries are generated by the model through the server-side search_context tool.

Headers

Header	Description
`Authorization`	Alchemyst API key or OpenRouter key.
`x-llm-api-key`	Provider LLM key, if not sent in the body.
`x-llm-base-url`	Provider base URL, if not sent in the body.
`x-user-email`	Optional email fallback for OpenRouter-only first requests.
`x-session-id`	Optional session grouping fallback.
`x-request-id`	Optional request id for tracing.

Server-side tools

The API injects tools before forwarding the request upstream:

search_context — searches the user’s private context. The model calls this whenever the question may be answerable from the user’s documents, memories, or previous conversations.
add_memory — available for existing accounts and claimed placeholders. The model calls it only when the user explicitly asks to remember or save something.

For unclaimed OpenRouter placeholder accounts, every turn is saved to memory automatically, so add_memory is not attached. If no relevant context is found, the model answers from its own knowledge rather than refusing.

Example: OpenAI SDK

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL:
    'https://platform-backend.getalchemystai.com/api/v1/context/search/chat',
  apiKey: process.env.ALCHEMYST_API_KEY,
});

const completion = await client.chat.completions.create({
  model: 'Big Bull Alpha',
  messages: [{ role: 'user', content: 'What did we decide about pricing?' }],
  llm_api_key: process.env.OPENROUTER_API_KEY,
} as any);

console.log(completion.choices[0].message.content);

The SDK appends /chat/completions to the baseURL, so the example above targets POST /api/v1/context/search/chat/completions.

Example: curl

curl -X POST \
  'https://platform-backend.getalchemystai.com/api/v1/context/search/chat/completions?context=true' \
  -H 'Authorization: Bearer sk-or-...' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "you@example.com",
    "model": "Big Bull Alpha",
    "messages": [
      { "role": "user", "content": "Summarize my saved project notes." }
    ]
  }'

Response

Non-streaming responses use the OpenAI chat completion shape:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "Big Bull Alpha",
  "provider": "Alchemyst AI",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 50,
    "total_tokens": 150
  },
  "context": "..."
}

context is only present when ?context=true is passed. model is white-labelled back to the Alchemyst name when the request used an Alchemyst model. When stream: true, the response is proxied as text/event-stream. The response includes x-alchemyst-upstream-latency-ms with the upstream model latency.

Models

The endpoint exposes OpenAI-compatible model listing routes:

Method	Route	Description
`GET`	`/api/v1/context/search/models`	List served models.
`GET`	`/api/v1/context/search/chat/models`	The same list at the `/chat` base path used by OpenAI SDK clients.

Point an OpenAI SDK client at the /chat base URL and call client.models.list() to use GET /api/v1/context/search/chat/models. Big Bull Alpha is the default, Alchemyst-served model; any OpenRouter provider/model id is also accepted.

Errors

Errors use the OpenAI error shape:

{
  "error": {
    "message": "Invalid request body.",
    "type": "invalid_request_error",
    "code": "invalid_request_error"
  }
}

Status	Meaning
400	Invalid body, query, base URL, missing LLM key, or invalid threshold order.
401	Missing/invalid Alchemyst or OpenRouter authentication.
402	Account is not allowed to perform `context.search`.
403	Missing `platform.context.search` scope.
500	Internal server error.
502	Upstream returned non-JSON, or OpenRouter could not be reached.
504	Upstream model request timed out.

Upstream provider errors are passed through with their original status and JSON body where possible.

GET /api/v1/context/search/models — list served models.
GET /api/v1/context/search/chat/models — the same list at the /chat base path used by OpenAI SDK clients.

Billing

Only context retrieval (context.search, measured in retrieved bytes) is billed. The Big Bull Alpha model is free while in launch. When using your own OpenRouter key, model usage is billed by OpenRouter.

API documentation

Models

Endpoint examples

Chat completions

Authentication

Request

Query parameters

Body

Headers

Server-side tools

Example: OpenAI SDK

Example: curl

Response

Models

Errors

Billing

See also

​Authentication

​Request

​Query parameters

​Body

​Headers

​Server-side tools

​Example: OpenAI SDK

​Example: curl

​Response

​Models

​Errors

​Related endpoints

​Billing

​See also

Authentication

Request

Query parameters

Body

Headers

Server-side tools

Example: OpenAI SDK

Example: curl

Response

Models

Errors

Related endpoints

Billing

See also