ReferenceAPI reference
Memory
19 operations in the Memory group.
6 of 19 operations on this page are generated contract stubs: the routes are real, the schemas are placeholders pending the owning subsystem's contract pass.
GET /api/memory/proposals
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: getApiMemoryProposals
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
GET /api/memory/proposals/{proposal}/policy-promotion
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: getApiMemoryProposalsProposalPolicyPromotion
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
proposal | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
POST /api/memory/proposals/{proposal}/policy-promotion/open-pr
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: postApiMemoryProposalsProposalPolicyPromotionOpenPr
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
proposal | path | yes | string |
Request body — application/json · object
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 201 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
POST /api/memory/proposals/batch-apply
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: postApiMemoryProposalsBatchApply
Request body — application/json · object
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 201 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
GET /api/memory/receipts
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: getApiMemoryReceipts
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
GET /api/memory/search
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: getApiMemorySearch
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
GET /api/resources/{workspace}/context-sources
Operation ID: listContextSources
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | List context sources visible in the selected workspace/team scope. Response is metadata-only and never returns indexed plaintext, embeddings, or provider credentials. | ContextSourceCollectionResponse |
POST /api/resources/{workspace}/context-sources
Operation ID: createContextSource
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string |
Request body — application/json · ContextSourceUpsertRequest (required)
| Field | Type | Required |
|---|---|---|
scope | enum(org, team) | no |
provider_type | enum(git, notion, confluence, viewport_memory) | no |
name | string | no |
description | `string | null` |
external_ref | string | no |
source_url | `string | null` |
scope_config | object | no |
execution_mode | enum(viewport_managed, customer_managed_context_worker, runner_local) | no |
content_storage | enum(none_metadata_only, managed_index, customer_index) | no |
read_enabled | boolean | no |
write_enabled | boolean | no |
default_update_strategy | enum(git_pr, viewport_inbox_then_provider_write, read_only) | no |
privacy_label | string | no |
freshness_status | string | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Create a provider-backed context source. UI writes do not create policy grants; access remains team/resource-scoped. | ContextSourceResponse |
GET /api/resources/{workspace}/context-sources/{contextSource}
Operation ID: showContextSource
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
contextSource | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Show a context source visible in the selected workspace/team scope. Response is metadata-only. | ContextSourceResponse |
PUT /api/resources/{workspace}/context-sources/{contextSource}
Operation ID: replaceContextSource
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
contextSource | path | yes | string |
Request body — application/json · ContextSourceUpsertRequest (required)
| Field | Type | Required |
|---|---|---|
scope | enum(org, team) | no |
provider_type | enum(git, notion, confluence, viewport_memory) | no |
name | string | no |
description | `string | null` |
external_ref | string | no |
source_url | `string | null` |
scope_config | object | no |
execution_mode | enum(viewport_managed, customer_managed_context_worker, runner_local) | no |
content_storage | enum(none_metadata_only, managed_index, customer_index) | no |
read_enabled | boolean | no |
write_enabled | boolean | no |
default_update_strategy | enum(git_pr, viewport_inbox_then_provider_write, read_only) | no |
privacy_label | string | no |
freshness_status | string | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Replace context-source metadata/configuration. This does not grant new policy access. | ContextSourceResponse |
PATCH /api/resources/{workspace}/context-sources/{contextSource}
Operation ID: updateContextSource
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
contextSource | path | yes | string |
Request body — application/json · ContextSourceUpsertRequest (required)
| Field | Type | Required |
|---|---|---|
scope | enum(org, team) | no |
provider_type | enum(git, notion, confluence, viewport_memory) | no |
name | string | no |
description | `string | null` |
external_ref | string | no |
source_url | `string | null` |
scope_config | object | no |
execution_mode | enum(viewport_managed, customer_managed_context_worker, runner_local) | no |
content_storage | enum(none_metadata_only, managed_index, customer_index) | no |
read_enabled | boolean | no |
write_enabled | boolean | no |
default_update_strategy | enum(git_pr, viewport_inbox_then_provider_write, read_only) | no |
privacy_label | string | no |
freshness_status | string | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Update context-source metadata/configuration. This does not grant new policy access. | ContextSourceResponse |
POST /api/resources/{workspace}/context-sources/{contextSource}/indexes
Operation ID: upsertContextSourceIndexes
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
contextSource | path | yes | string |
Request body — application/json · ContextSourceIndexUpsertRequest (required)
| Field | Type | Required |
|---|---|---|
documents | array<ContextSourceIndexUpsertDocument> | yes |
sync_mode | enum(merge, replace_missing) | no |
generate_embeddings | boolean | no |
embedding_model | `string | null` |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Upserted managed context-source index blocks. Response is digest-only and never returns indexed plaintext. | ContextSourceIndexUpsertResponse |
POST /api/resources/{workspace}/context-sources/{contextSource}/sync-git
Operation ID: syncGitContextSource
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
contextSource | path | yes | string |
Request body — application/json · ContextSourceGitSyncRequest
| Field | Type | Required |
|---|---|---|
limit | integer | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Synced a Viewport-managed Git context source through a connected GitHub App installation. Response is digest-only and never returns indexed plaintext. | ContextSourceGitSyncResponse |
GET /api/resources/{workspace}/memory/proposals
Operation ID: listMemoryProposals
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
status | query | no | string | |
queue_bucket | query | no | string | |
recommended_action | query | no | string | |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Digest-only memory/context update proposal queue scoped to the current workspace/team. Raw patches and memory plaintext are never returned. | MemoryProposalCollectionResponse |
GET /api/resources/{workspace}/memory/proposals/{proposal}/policy-promotion
Build a digest-only policy-promotion packet for a memory proposal
Operation ID: getMemoryPolicyPromotion
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
proposal | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Digest-only policy-promotion packet. | MemoryPolicyPromotionPacketResponse |
| 403 | Forbidden. | — |
| 404 | Not found. | — |
| 422 | Proposal is not eligible for policy promotion. | — |
POST /api/resources/{workspace}/memory/proposals/{proposal}/policy-promotion/open-pr
Open a GitOps pull request that promotes a memory rule into enforceable policy
Operation ID: openMemoryPolicyPromotionPullRequest
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
proposal | path | yes | string |
Request body — application/json · MemoryPolicyPromotionPullRequestRequest (required)
| Field | Type | Required |
|---|---|---|
source_id | string | yes |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Existing policy promotion pull request updated. | MemoryPolicyPromotionPullRequestResponse |
| 201 | Policy promotion pull request opened. | MemoryPolicyPromotionPullRequestResponse |
| 403 | Forbidden. | — |
| 404 | Not found. | — |
| 422 | Proposal, source, or target policy is not eligible for policy promotion. | — |
POST /api/resources/{workspace}/memory/proposals/batch-apply
Operation ID: batchApplyMemoryProposals
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string |
Request body — application/json · MemoryProposalBatchApplyRequest (required)
| Field | Type | Required |
|---|---|---|
proposal_ids | array<string> | yes |
message | `string | null` |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Human-initiated batch application for deterministically low-risk managed memory proposals. Only eligible same-team proposals are applied; raw patches and memory plaintext are never returned. | MemoryProposalBatchApplyResponse |
GET /api/resources/{workspace}/memory/receipts
Operation ID: listMemoryReceipts
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
run_id | query | no | string | |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Digest-only memory-use receipt summaries scoped to the current workspace/team. Raw run event payloads and memory plaintext are never returned. | MemoryReceiptCollectionResponse |
GET /api/resources/{workspace}/memory/search
Operation ID: searchMemory
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
q | query | yes | string | |
limit | query | no | integer | |
source_kind | query | no | enum(all, approved_memory, managed_context_index) | Restricts retrieval to approved governed memory, managed context indexes, or both. Defaults to all. |
context_source_ids | query | no | array<string> | Optional selected managed context source ids. Applies only to managed context index retrieval; inaccessible source ids silently return no citations. |
query_embedding | query | no | array<number> | Optional caller-supplied query embedding used only against managed context index entries that carry stored embeddings. The vector itself is never returned. |
generate_query_embedding | query | no | boolean | When true, Viewport generates a hosted query embedding for managed-index retrieval if query_embedding is not supplied. Fails closed if the configured embedding provider is unavailable. |
query_embedding_model | query | no | `string | null` |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Governed memory metadata search. Rule memories are returned only as policy-promotion candidates and raw memory plaintext is never returned. | MemorySearchResponse |