API · 2.0.0

Memory

Embedded notes with PRIVATE / PROJECT / 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.
`projectId`	query	no	`string`	Restrict to a single Project.
`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 1536-dim vector (OpenAI text-embedding-3-small).
`visibility`	`Visibility`	yes
`projectId`	`string`	no	Required when visibility=PROJECT.
`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
`projectId`	`string`	no	Optional Project 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 '{ ... }'