API · 2.0.0

Memory

Embedded notes with PRIVATE / SPACE / ORG visibility.

4 operations. All requests need Authorization: Bearer sk_.... Responses use the standard envelope; see overview for shapes and error codes.

get/memory

List memories visible to the caller

Parameters

Name	In	Required	Type	Description
`visibility`	query	no	`Visibility`	Filter by visibility. Defaults to all visible to caller.
`spaceId`	query	no	`string`	Restrict to a single Space.
`limit`	query	no	`integer`

Responses

200 — Memories.
400 — Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
401 — Missing or invalid auth. `error.code = AUTH_ERROR`.
403 — Authenticated but not allowed (wrong role, not a member, or org scope mismatch). `error.code = FORBIDDEN`.
404 — Resource does not exist or is invisible to the caller. `error.code = NOT_FOUND`.
409 — Conflict — duplicate slug, race condition, or invalid state transition. `error.code = CONFLICT`.
429 — Rate limit exceeded. `error.code = RATE_LIMIT`. Retry after the window listed in `Retry-After`.
500 — Unexpected server error. `error.code = INTERNAL_ERROR`. Logged with the `requestId` echoed in metadata.

cURL example

curl -X GET https://switchy.build/api/memory \
  -H 'Authorization: Bearer sk_live_...' \

post/memory

Create a memory

Parameters

Name	In	Required	Type	Description
`Idempotency-Key`	header	no	`string`	Opaque client-generated UUID. The first request wins; identical follow-ups within 24h return the original response. Recommended on all POST endpoints.

Request body

Field	Type	Required	Description
`content`	`string`	yes	Plain text. Will be embedded into a 384-dim vector.
`visibility`	`Visibility`	yes
`spaceId`	`string`	no	Required when visibility=SPACE.
`tags`	`string[]`	no
`sourceUrl`	`string`	no

Responses

201 — Created memory.
400 — Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
401 — Missing or invalid auth. `error.code = AUTH_ERROR`.
403 — Authenticated but not allowed (wrong role, not a member, or org scope mismatch). `error.code = FORBIDDEN`.
404 — Resource does not exist or is invisible to the caller. `error.code = NOT_FOUND`.
409 — Conflict — duplicate slug, race condition, or invalid state transition. `error.code = CONFLICT`.
429 — Rate limit exceeded. `error.code = RATE_LIMIT`. Retry after the window listed in `Retry-After`.
500 — Unexpected server error. `error.code = INTERNAL_ERROR`. Logged with the `requestId` echoed in metadata.

cURL example

curl -X POST https://switchy.build/api/memory \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

delete/memory/{memoryId}

Delete a memory

Parameters

Name	In	Required	Type	Description
`memoryId`	path	yes	`string`	CUID

Responses

204 — Deleted.
400 — Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
401 — Missing or invalid auth. `error.code = AUTH_ERROR`.
403 — Authenticated but not allowed (wrong role, not a member, or org scope mismatch). `error.code = FORBIDDEN`.
404 — Resource does not exist or is invisible to the caller. `error.code = NOT_FOUND`.
409 — Conflict — duplicate slug, race condition, or invalid state transition. `error.code = CONFLICT`.
429 — Rate limit exceeded. `error.code = RATE_LIMIT`. Retry after the window listed in `Retry-After`.
500 — Unexpected server error. `error.code = INTERNAL_ERROR`. Logged with the `requestId` echoed in metadata.

cURL example

curl -X DELETE https://switchy.build/api/memory/:memoryId \
  -H 'Authorization: Bearer sk_live_...' \

post/memory/search

Semantic search across visible memories

Embeds the query, runs vector search, and re-ranks. Visibility is enforced inside the SQL query — you cannot see a teammate's PRIVATE memory.

Request body

Field	Type	Required	Description
`query`	`string`	yes
`spaceId`	`string`	no	Optional Space scope.
`limit`	`integer`	no

Responses

200 — Ranked matches with scores.
400 — Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
401 — Missing or invalid auth. `error.code = AUTH_ERROR`.
403 — Authenticated but not allowed (wrong role, not a member, or org scope mismatch). `error.code = FORBIDDEN`.
404 — Resource does not exist or is invisible to the caller. `error.code = NOT_FOUND`.
409 — Conflict — duplicate slug, race condition, or invalid state transition. `error.code = CONFLICT`.
429 — Rate limit exceeded. `error.code = RATE_LIMIT`. Retry after the window listed in `Retry-After`.
500 — Unexpected server error. `error.code = INTERNAL_ERROR`. Logged with the `requestId` echoed in metadata.

cURL example

curl -X POST https://switchy.build/api/memory/search \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'