Create a Memory Store

Creates a Memory Store container. Create the Store alone, or use the optional mount field to mount it to an (identity, template) pair after creation.

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.
`mount`	object	No	Mount to establish after creation. Both `identity_id` and `template_id` are required when supplied.
`mount.identity_id`	string	Conditional	Identity ID (`idn_...`). Required when `mount` is supplied.
`mount.template_id`	string	Conditional	Template ID (`tmpl_...`). Required when `mount` is supplied.

Direct mounting follows the same rules as Mount a Memory Store: the Store must be user-created and active, the permission is always read_only, and each (identity, template) pair supports at most 10 explicit Store mounts. The created Store remains system_managed=false and does not become the system Default Memory Store.

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"},
    "mount": {
      "identity_id": "idn_63ee28747a35cff93771c491",
      "template_id": "tmpl_eb3377fb74ad413e17b3d755"
    }
  }'

To create only the Store, omit mount.

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": 1
  }
}

When mount is supplied, mounting completes before the response is returned, so binding_info.identity_template_count includes the new mount. Retrying with the same Idempotency-Key and request body resumes mounting the same Store without creating a duplicate Store or mount.

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`, `Idempotency-Key` is missing, either ID is missing from `mount`, or the limit of 10 explicit mounts has been reached.
401	`authentication_error`	The authentication token is missing or invalid.
403	`permission_error`	The caller cannot create the resource.
404	`not_found_error`	The Identity or Template specified by `mount` does not exist or is not visible to the caller.
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