{ "components": { "schemas": { "AcknowledgeInboxRequest": { "additionalProperties": false, "properties": { "expectedCursor": { "type": [ "string", "null" ] }, "throughCursor": { "type": "string" } }, "required": [ "throughCursor" ], "type": "object" }, "AcknowledgeInboxResponse": { "additionalProperties": false, "properties": { "acknowledgedCursor": { "type": "string" }, "replayed": { "type": "boolean" } }, "required": [ "acknowledgedCursor", "replayed" ], "type": "object" }, "AppendMessageRequest": { "additionalProperties": false, "properties": { "bodyMarkdown": { "type": "string" }, "mentions": { "items": { "$ref": "#/components/schemas/MentionBinding" }, "type": "array" } }, "required": [ "bodyMarkdown" ], "type": "object" }, "ErrorBody": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "type": "object" }, "ErrorEnvelope": { "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } }, "required": [ "error" ], "type": "object" }, "InboxPageResponse": { "additionalProperties": false, "properties": { "acknowledgedCursor": { "type": [ "string", "null" ] }, "items": { "items": { "$ref": "#/components/schemas/NotificationResponse" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items" ], "type": "object" }, "MentionBinding": { "additionalProperties": false, "properties": { "endByte": { "format": "int32", "minimum": 0, "type": "integer" }, "principalId": { "type": "string" }, "principalKind": { "$ref": "#/components/schemas/MentionPrincipalKind" }, "startByte": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "principalKind", "principalId", "startByte", "endByte" ], "type": "object" }, "MentionPrincipalKind": { "enum": [ "human", "bot" ], "type": "string" }, "MentionSpan": { "additionalProperties": false, "properties": { "endByte": { "format": "int32", "minimum": 0, "type": "integer" }, "startByte": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "startByte", "endByte" ], "type": "object" }, "Message": { "additionalProperties": false, "properties": { "authorizationDecisionId": { "type": [ "string", "null" ] }, "authorizingSubjectId": { "type": [ "string", "null" ] }, "authorizingSubjectKind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubjectKind" } ] }, "bodyBytes": { "format": "int32", "minimum": 0, "type": "integer" }, "bodyMarkdown": { "type": "string" }, "botCredentialId": { "type": [ "string", "null" ] }, "botGrantId": { "type": [ "string", "null" ] }, "branchId": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "idempotencyKey": { "type": "string" }, "mentions": { "items": { "$ref": "#/components/schemas/MentionBinding" }, "type": "array" }, "messageId": { "type": "string" }, "repositoryId": { "type": "string" }, "requestId": { "type": "string" }, "roomId": { "type": "string" }, "senderId": { "type": "string" }, "senderKind": { "$ref": "#/components/schemas/SenderKind" } }, "required": [ "messageId", "roomId", "repositoryId", "senderKind", "senderId", "requestId", "bodyMarkdown", "bodyBytes", "createdAt", "idempotencyKey" ], "type": "object" }, "MessagePageResponse": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/MessageResponse" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items" ], "type": "object" }, "MessageResponse": { "additionalProperties": false, "properties": { "authorizationDecisionId": { "type": [ "string", "null" ] }, "authorizingSubjectId": { "type": [ "string", "null" ] }, "authorizingSubjectKind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubjectKind" } ] }, "bodyBytes": { "format": "int32", "minimum": 0, "type": "integer" }, "bodyMarkdown": { "type": "string" }, "botCredentialId": { "type": [ "string", "null" ] }, "botGrantId": { "type": [ "string", "null" ] }, "branchId": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "idempotencyKey": { "type": "string" }, "mentions": { "items": { "$ref": "#/components/schemas/MentionBinding" }, "type": "array" }, "messageId": { "type": "string" }, "renderPolicy": { "type": "string" }, "renderedHtml": { "type": "string" }, "repositoryId": { "type": "string" }, "requestId": { "type": "string" }, "roomId": { "type": "string" }, "senderId": { "type": "string" }, "senderKind": { "$ref": "#/components/schemas/SenderKind" } }, "required": [ "bodyBytes", "bodyMarkdown", "createdAt", "idempotencyKey", "messageId", "renderPolicy", "renderedHtml", "repositoryId", "requestId", "roomId", "senderId", "senderKind" ], "type": "object" }, "Notification": { "additionalProperties": false, "properties": { "branchId": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "messageId": { "type": "string" }, "notificationId": { "type": "string" }, "repositoryId": { "type": "string" }, "roomId": { "type": "string" }, "senderId": { "type": "string" }, "senderKind": { "$ref": "#/components/schemas/SenderKind" }, "spans": { "items": { "$ref": "#/components/schemas/MentionSpan" }, "type": "array" }, "targetId": { "type": "string" }, "targetKind": { "$ref": "#/components/schemas/MentionPrincipalKind" } }, "required": [ "notificationId", "targetKind", "targetId", "repositoryId", "roomId", "messageId", "senderKind", "senderId", "spans", "createdAt" ], "type": "object" }, "NotificationResponse": { "additionalProperties": false, "properties": { "acknowledged": { "type": "boolean" }, "branchId": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "cursor": { "type": "string" }, "messageId": { "type": "string" }, "notificationId": { "type": "string" }, "repositoryId": { "type": "string" }, "roomId": { "type": "string" }, "senderId": { "type": "string" }, "senderKind": { "$ref": "#/components/schemas/SenderKind" }, "spans": { "items": { "$ref": "#/components/schemas/MentionSpan" }, "type": "array" }, "targetId": { "type": "string" }, "targetKind": { "$ref": "#/components/schemas/MentionPrincipalKind" } }, "required": [ "acknowledged", "createdAt", "cursor", "messageId", "notificationId", "repositoryId", "roomId", "senderId", "senderKind", "spans", "targetId", "targetKind" ], "type": "object" }, "RoomKind": { "enum": [ "repository", "branch" ], "type": "string" }, "RoomResponse": { "additionalProperties": false, "properties": { "branchId": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/RoomKind" }, "lastMessageAt": { "format": "date-time", "type": [ "string", "null" ] }, "messageCount": { "format": "int64", "minimum": 0, "type": "integer" }, "persisted": { "type": "boolean" }, "repositoryId": { "type": "string" }, "roomId": { "type": [ "string", "null" ] }, "sealedAt": { "format": "date-time", "type": [ "string", "null" ] }, "state": { "$ref": "#/components/schemas/RoomState" }, "version": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] } }, "required": [ "repositoryId", "kind", "state", "persisted", "messageCount" ], "type": "object" }, "RoomState": { "enum": [ "active", "sealed" ], "type": "string" }, "SenderKind": { "enum": [ "user", "bot" ], "type": "string" }, "SubjectKind": { "enum": [ "user", "organization" ], "type": "string" } }, "securitySchemes": { "botBearer": { "bearerFormat": "Gitdown bot access token", "description": "Grant-bound bot identity. Live room:read or message:append capability is required and human/app tokens are not reclassified as bots.", "scheme": "bearer", "type": "http" }, "chatOAuthBearer": { "bearerFormat": "Gitdown Chat OAuth access token", "description": "Chat-audience human OAuth identity. Live repository read/write authority is required and Firebase or marketplace app tokens are rejected.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Code-generated external contract for repository-global and branch-scoped Chat rooms, immutable messages, and resumable SSE streams. Human OAuth and bot access tokens are authorized live against core for every operation and long-lived streams are rechecked periodically.", "title": "Gitdown Chat External API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/repositories/{repositoryId}/branches/{branchId}/room": { "get": { "operationId": "getBranchRoom", "parameters": [ { "description": "Canonical repository ULID", "in": "path", "name": "repositoryId", "required": true, "schema": { "type": "string" } }, { "description": "Canonical branch ULID", "in": "path", "name": "branchId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomResponse" } } }, "description": "Persisted or empty virtual branch room" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid scope or request ID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bearer token rejected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Repository or branch read denied" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authorization or persistence unavailable" } }, "security": [ { "chatOAuthBearer": [] }, { "botBearer": [] } ], "tags": [ "rooms" ] } }, "/v1/repositories/{repositoryId}/branches/{branchId}/room/events": { "get": { "operationId": "streamBranchRoom", "parameters": [ { "description": "Canonical repository ULID", "in": "path", "name": "repositoryId", "required": true, "schema": { "type": "string" } }, { "description": "Canonical branch ULID", "in": "path", "name": "branchId", "required": true, "schema": { "type": "string" } }, { "description": "Last durable message cursor", "in": "header", "name": "Last-Event-ID", "required": false, "schema": { "type": [ "string", "null" ] } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "SSE message, heartbeat, handoff, and reauthorize events. Only message events carry durable IDs." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid scope, cursor, or conflicting resume inputs" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bearer token rejected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Repository or branch read denied" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Virtual room cannot be materialized because the scope is sealed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Per-principal or per-room stream cap reached", "headers": { "Retry-After": { "description": "Seconds before connection admission should be retried", "schema": { "format": "int64", "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authorization, persistence, or listener unavailable" } }, "security": [ { "chatOAuthBearer": [] }, { "botBearer": [] } ], "tags": [ "streams" ] } }, "/v1/repositories/{repositoryId}/branches/{branchId}/room/messages": { "get": { "operationId": "listBranchMessages", "parameters": [ { "description": "Canonical repository ULID", "in": "path", "name": "repositoryId", "required": true, "schema": { "type": "string" } }, { "description": "Canonical branch ULID", "in": "path", "name": "branchId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagePageResponse" } } }, "description": "Oldest-first message page" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid scope, limit, cursor, or request ID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bearer token rejected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Repository or branch read denied" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authorization or persistence unavailable" } }, "security": [ { "chatOAuthBearer": [] }, { "botBearer": [] } ], "tags": [ "messages" ] }, "post": { "operationId": "appendBranchMessage", "parameters": [ { "description": "Canonical repository ULID", "in": "path", "name": "repositoryId", "required": true, "schema": { "type": "string" } }, { "description": "Canonical branch ULID", "in": "path", "name": "branchId", "required": true, "schema": { "type": "string" } }, { "description": "Canonical ULID scoped to the authenticated sender and room", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } }, { "description": "Bearer-form Core OAuth resource credential; required only for human-authored structured mentions", "in": "header", "name": "X-Gitdown-Core-Authorization", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendMessageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } }, "description": "Idempotent replay of the original immutable branch message" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } }, "description": "Immutable branch message appended" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid message, scope, header, or request ID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bearer token rejected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Repository/branch write or bot append capability denied" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Room sealed or resource conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Shared append limit exceeded", "headers": { "Retry-After": { "description": "Whole seconds until the shared fixed window resets", "schema": { "format": "int64", "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authorization or persistence unavailable" } }, "security": [ { "chatOAuthBearer": [] }, { "botBearer": [] } ], "tags": [ "messages" ] } }, "/v1/repositories/{repositoryId}/inbox": { "get": { "operationId": "listRepositoryInbox", "parameters": [ { "description": "Canonical repository ULID", "in": "path", "name": "repositoryId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxPageResponse" } } }, "description": "Bounded page of mention notifications" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid scope, limit, cursor, or request ID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bearer token rejected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Repository read denied" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authorization or persistence unavailable" } }, "security": [ { "chatOAuthBearer": [] }, { "botBearer": [] } ], "tags": [ "inbox" ] } }, "/v1/repositories/{repositoryId}/inbox/acknowledgements": { "post": { "operationId": "acknowledgeRepositoryInbox", "parameters": [ { "description": "Canonical repository ULID", "in": "path", "name": "repositoryId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgeInboxRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgeInboxResponse" } } }, "description": "Inbox checkpoint updated or replayed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid scope, cursor, or request ID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bearer token rejected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Repository read denied" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Notification unavailable to this principal" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Expected checkpoint is stale" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authorization or persistence unavailable" } }, "security": [ { "chatOAuthBearer": [] }, { "botBearer": [] } ], "tags": [ "inbox" ] } }, "/v1/repositories/{repositoryId}/inbox/events": { "get": { "operationId": "streamRepositoryInbox", "parameters": [ { "description": "Canonical repository ULID", "in": "path", "name": "repositoryId", "required": true, "schema": { "type": "string" } }, { "description": "Last durable notification cursor", "in": "header", "name": "Last-Event-ID", "required": false, "schema": { "type": [ "string", "null" ] } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "SSE notification, heartbeat, handoff, and reauthorize events. Only notification events carry durable IDs." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid scope, cursor, or conflicting resume inputs" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bearer token rejected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Repository read denied" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authorization or persistence unavailable" } }, "security": [ { "chatOAuthBearer": [] }, { "botBearer": [] } ], "tags": [ "inbox" ] } }, "/v1/repositories/{repositoryId}/room": { "get": { "operationId": "getRepositoryRoom", "parameters": [ { "description": "Canonical repository ULID", "in": "path", "name": "repositoryId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomResponse" } } }, "description": "Persisted or empty virtual repository room" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid scope or request ID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bearer token rejected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Repository read denied" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authorization or persistence unavailable" } }, "security": [ { "chatOAuthBearer": [] }, { "botBearer": [] } ], "tags": [ "rooms" ] } }, "/v1/repositories/{repositoryId}/room/events": { "get": { "operationId": "streamRepositoryRoom", "parameters": [ { "description": "Canonical repository ULID", "in": "path", "name": "repositoryId", "required": true, "schema": { "type": "string" } }, { "description": "Last durable message cursor", "in": "header", "name": "Last-Event-ID", "required": false, "schema": { "type": [ "string", "null" ] } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "SSE message, heartbeat, handoff, and reauthorize events. Only message events carry durable IDs." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid scope, cursor, or conflicting resume inputs" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bearer token rejected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Repository read denied" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Virtual room cannot be materialized because the scope is sealed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Per-principal or per-room stream cap reached", "headers": { "Retry-After": { "description": "Seconds before connection admission should be retried", "schema": { "format": "int64", "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authorization, persistence, or listener unavailable" } }, "security": [ { "chatOAuthBearer": [] }, { "botBearer": [] } ], "tags": [ "streams" ] } }, "/v1/repositories/{repositoryId}/room/messages": { "get": { "operationId": "listRepositoryMessages", "parameters": [ { "description": "Canonical repository ULID", "in": "path", "name": "repositoryId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagePageResponse" } } }, "description": "Oldest-first message page" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid scope, limit, cursor, or request ID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bearer token rejected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Repository read denied" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authorization or persistence unavailable" } }, "security": [ { "chatOAuthBearer": [] }, { "botBearer": [] } ], "tags": [ "messages" ] }, "post": { "operationId": "appendRepositoryMessage", "parameters": [ { "description": "Canonical repository ULID", "in": "path", "name": "repositoryId", "required": true, "schema": { "type": "string" } }, { "description": "Canonical ULID scoped to the authenticated sender and room", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } }, { "description": "Bearer-form Core OAuth resource credential; required only for human-authored structured mentions", "in": "header", "name": "X-Gitdown-Core-Authorization", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendMessageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } }, "description": "Idempotent replay of the original immutable message" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } }, "description": "Immutable message appended" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid message, scope, header, or request ID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bearer token rejected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Repository write or bot append capability denied" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Room sealed or resource conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Shared append limit exceeded", "headers": { "Retry-After": { "description": "Whole seconds until the shared fixed window resets", "schema": { "format": "int64", "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authorization or persistence unavailable" } }, "security": [ { "chatOAuthBearer": [] }, { "botBearer": [] } ], "tags": [ "messages" ] } } }, "x-gitdown-error-codes": [ "AUTHENTICATION_REQUIRED", "AUTHORIZATION_DENIED", "AUTHORIZATION_REQUEST_INVALID", "AUTHORIZATION_UNAVAILABLE", "CORE_RESOURCE_TOKEN_REJECTED", "CORE_RESOURCE_TOKEN_REQUIRED", "CURSOR_CONFLICT", "CURSOR_INVALID", "CURSOR_UNAVAILABLE", "IDEMPOTENCY_KEY_INVALID", "IDEMPOTENCY_KEY_REUSED", "INBOX_CHECKPOINT_STALE", "LIMIT_INVALID", "MESSAGE_BUILD_FAILED", "MESSAGE_INVALID", "MENTION_INVALID", "MENTION_TARGET_INVALID", "RATE_LIMITED", "REQUEST_ID_INVALID", "REQUEST_INVALID", "RESOURCE_CONFLICT", "RESOURCE_NOT_FOUND", "RESPONSE_INVALID", "ROOM_CREATE_UNAVAILABLE", "ROOM_INCOHERENT", "ROOM_SEALED", "SCOPE_INVALID", "STORE_UNAVAILABLE", "STREAM_HANDOFF_FAILED", "STREAM_PRINCIPAL_LIMIT", "STREAM_ROOM_LIMIT", "STREAM_TARGET_INVALID", "STREAM_UNAVAILABLE", "TOKEN_REJECTED" ] }