{"openapi":"3.0.3","info":{"title":"RPP Gateway Integration API","version":"1.1.0","description":"Public developer contract for organization-scoped integration API keys. Includes channel discovery, payload publication, and payload delivery operations. Staff administration is intentionally excluded."},"servers":[{"url":"/","description":"Same origin as the deployed Gateway instance"}],"tags":[{"name":"Channels"},{"name":"Publication"},{"name":"Delivery"}],"paths":{"/api/v1/channels":{"get":{"tags":["Channels"],"summary":"List channels visible to an integration key","operationId":"listVisibleChannels","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Active granted channels in the key's organization","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/channels/{channel_slug}/payloads":{"post":{"tags":["Publication"],"summary":"Publish an opaque payload idempotently","operationId":"publishPayload","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ChannelSlug"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/PayloadMetadata"}],"requestBody":{"required":true,"description":"Raw opaque payload bytes using the caller-supplied Content-Type, including JSON, XML, CSV, ZIP, or other bounded media types.","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"$ref":"#/components/responses/PublishedPayload"},"201":{"$ref":"#/components/responses/PublishedPayload"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/payloads":{"get":{"tags":["Delivery"],"summary":"Poll ready payloads","operationId":"listPendingPayloads","security":[{"bearerAuth":[]}],"parameters":[{"name":"channel","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Ready payloads in the key's organization/grants","content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ConsumerPayload"}},"next_cursor":{"type":"string","nullable":true}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/payloads/{payload_id}/claim":{"post":{"tags":["Delivery"],"summary":"Claim or recover a payload claim","operationId":"claimPayload","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PayloadId"}],"responses":{"200":{"description":"Current processing attempt","content":{"application/json":{"schema":{"type":"object","required":["payload","attempt","idempotent_replay"],"properties":{"payload":{"$ref":"#/components/schemas/ConsumerPayload"},"attempt":{"$ref":"#/components/schemas/PayloadAttempt"},"idempotent_replay":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/api/v1/payloads/{payload_id}/content":{"get":{"tags":["Delivery"],"summary":"Download content under the current owning attempt","operationId":"downloadPayload","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PayloadId"},{"name":"attempt_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Verified payload bytes","headers":{"Content-Type":{"description":"Original stored media type","schema":{"type":"string"}},"Content-Length":{"description":"Exact payload size in bytes","schema":{"type":"integer","minimum":0}},"Content-Disposition":{"description":"Safe attachment filename disposition","schema":{"type":"string"}},"X-RPP-Payload-Id":{"schema":{"type":"string","format":"uuid"}},"X-RPP-Checksum-SHA256":{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}}},"content":{"*/*":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/payloads/{payload_id}/complete":{"post":{"tags":["Delivery"],"summary":"Complete the current owning attempt","operationId":"completePayload","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PayloadId"}],"requestBody":{"$ref":"#/components/requestBodies/AttemptRequest"},"x-postman-example":{"attempt_id":"{{attemptId}}"},"responses":{"200":{"$ref":"#/components/responses/LifecyclePayload"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/api/v1/payloads/{payload_id}/fail":{"post":{"tags":["Delivery"],"summary":"Fail the current owning attempt","operationId":"failPayload","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PayloadId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["attempt_id","error_message"],"properties":{"attempt_id":{"type":"string","format":"uuid"},"error_message":{"type":"string","minLength":1,"maxLength":4000}}},"example":{"attempt_id":"00000000-0000-4000-8000-000000000000","error_message":"Import validation failed; review the partner import log."}}}},"x-postman-example":{"attempt_id":"{{attemptId}}","error_message":"Import validation failed; review the partner import log."},"responses":{"200":{"$ref":"#/components/responses/LifecyclePayload"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/api/v1/payloads/{payload_id}/retry":{"post":{"tags":["Delivery"],"summary":"Return an owned failed payload to ready","operationId":"retryFailedPayload","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PayloadId"}],"requestBody":{"$ref":"#/components/requestBodies/AttemptRequest"},"x-postman-example":{"attempt_id":"{{attemptId}}"},"responses":{"200":{"description":"Failed payload returned to ready","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/ConsumerPayload"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}}},"components":{"responses":{"BadRequest":{"description":"Invalid input or missing/malformed organization context","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Lifecycle, uniqueness, lock, disabled-organization, or current-state conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"Missing role, mandatory password change, channel permission, or exact origin","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"LifecyclePayload":{"description":"Lifecycle mutation applied or idempotently replayed","content":{"application/json":{"schema":{"type":"object","required":["payload","idempotent_replay"],"properties":{"payload":{"$ref":"#/components/schemas/ConsumerPayload"},"idempotent_replay":{"type":"boolean"}}}}}},"NotFound":{"description":"Resource absent or concealed outside selected/key organization","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"PayloadTooLarge":{"description":"Body exceeds configured limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"PublishedPayload":{"description":"Payload committed or exact replay returned","content":{"application/json":{"schema":{"type":"object","required":["payload","idempotent_replay"],"properties":{"payload":{"$ref":"#/components/schemas/ConsumerPayload"},"idempotent_replay":{"type":"boolean"}}}}}},"Unauthorized":{"description":"Missing or invalid authentication","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unavailable":{"description":"Required object storage, publication, or email dependency temporarily unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Channel":{"type":"object","required":["id","store_id","slug","display_name","description","status","max_payload_bytes","payload_retention_days"],"properties":{"id":{"type":"string","format":"uuid"},"store_id":{"type":"string","nullable":true,"format":"uuid"},"slug":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","disabled"]},"max_payload_bytes":{"type":"integer","minimum":1,"maximum":262144000,"description":"Channel limit. Publication enforces the lower of this value and the server ceiling."},"payload_retention_days":{"type":"integer","minimum":1,"maximum":365,"description":"Snapshotted onto each new payload and counted from processing completion."},"created_at":{"type":"string","format":"date-time"}}},"ConsumerPayload":{"type":"object","required":["id","channel_id","payload_type","schema_version","mode","original_filename","content_type","metadata","file_size","checksum_sha256","status","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"channel_id":{"type":"string","format":"uuid"},"payload_type":{"type":"string"},"schema_version":{"type":"string"},"mode":{"type":"string","enum":["full","delta"]},"original_filename":{"type":"string"},"content_type":{"type":"string"},"source_timestamp":{"type":"string","nullable":true,"format":"date-time"},"metadata":{"type":"object","additionalProperties":true},"file_size":{"type":"integer","minimum":0},"checksum_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"status":{"$ref":"#/components/schemas/PayloadStatus"},"attempt_count":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time"},"claimed_at":{"type":"string","nullable":true,"format":"date-time"},"completed_at":{"type":"string","nullable":true,"format":"date-time"},"failed_at":{"type":"string","nullable":true,"format":"date-time"},"latest_error":{"type":"string","nullable":true}}},"PayloadAttempt":{"type":"object","required":["id","attempt_number","status","claimed_at"],"properties":{"id":{"type":"string","format":"uuid"},"attempt_number":{"type":"integer","minimum":1},"status":{"type":"string","enum":["processing","processed","failed","requeued"]},"claimed_at":{"type":"string","format":"date-time"}}},"PayloadStatus":{"type":"string","enum":["ready","processing","processed","failed"]},"Problem":{"type":"object","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}},"requestBodies":{"AttemptRequest":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["attempt_id"],"properties":{"attempt_id":{"type":"string","format":"uuid"}}},"example":{"attempt_id":"00000000-0000-4000-8000-000000000000"}}}}},"parameters":{"ChannelSlug":{"name":"channel_slug","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^\\u0000-\\u001f\\u007f]+$"}},"PayloadId":{"name":"payload_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"PayloadMetadata":{"name":"X-RPP-Payload-Metadata","in":"header","required":true,"schema":{"type":"string","maxLength":12000},"description":"Canonical unpadded base64url of bounded UTF-8 JSON metadata."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"RPP Gateway integration API key","description":"Organization-scoped machine key with publish and/or consume; never staff administration."}}}}