Create a Memory Store

Creates a Memory Store container. The returned memstore_... ID can be mounted to an Identity and Template or used to create Memory entries directly.

Path

POST /api/v1/forward/memory_stores

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or admin SAT>`
`Idempotency-Key`	Yes	Idempotency key for the create request. The same key can only be reused with the same request body. Omitting it returns `400`.
`Content-Type`	Yes	`application/json`

Request body

Field	Type	Required	Description
`name`	string	Yes	Non-empty display name. Non-printable control characters (`U+0000`–`U+001F` and `U+007F`) are not allowed, except newline `\n`, carriage return `\r`, and tab `\t`.
`description`	string	No	Free-text description. Non-printable control characters are not allowed.
`metadata`	object	No	Key-value metadata whose values must be strings. Up to 15 keys; keys are 1–64 characters and values are up to 512 characters. `created_by` is reserved by Forward and is set to `"forward"` by the server. Supplying `created_by` returns `400 invalid_request_error`. See Store metadata constraints.

Example request

curl -X POST "https://api.qoder.com/api/v1/forward/memory_stores" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-alpha-store-v1" \
  -d '{
    "name": "project-alpha-memory",
    "description": "Agent knowledge base for project Alpha",
    "metadata": {"team": "backend"}
  }'

Example response

HTTP 200 OK

{
  "id": "memstore_00mc7mukn7lkxr454tjd",
  "type": "memory_store",
  "name": "project-alpha-memory",
  "description": "Agent knowledge base for project Alpha",
  "status": "active",
  "entry_count": 0,
  "total_size": 0,
  "metadata": {
    "team": "backend",
    "created_by": "forward"
  },
  "system_managed": false,
  "identity_id": null,
  "created_at": "2026-08-14T10:00:00Z",
  "updated_at": "2026-08-14T10:00:00Z",
  "archived_at": null,
  "binding_info": {
    "identity_template_count": 0
  }
}

Response

Returns a Memory Store object.

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	The request body is invalid: `name` is missing or contains control characters, metadata exceeds 15 keys or contains `created_by`, or `Idempotency-Key` is missing.
401	`authentication_error`	The authentication token is missing or invalid.
403	`permission_error`	The caller cannot create the resource.
409	`conflict_error`	The same `Idempotency-Key` was used with a different request body, or create recovery requires manual intervention.
500/502/503	`api_error`	Forward or a dependent service failed.

​Path

​Headers

​Request body

​Example request

​Example response

​Response