Skip to content
KataraKatara documentation

List owner-created promotion drafts

GET
/katara/v1/orgs/{org_id}/environment-promotions
curl --request GET \
  --url 'https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environment-promotions?source_environment_id=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0&destination_environment_id=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0&limit=25' \
  --header 'Authorization: Bearer <token>'

Returns at most 25 historical draft identifiers created by the current human owner in the selected Test/Live pair and current Test reset generation. Requires a signed-in human owner session and current authority in both environments. evidence_attached indicates a recorded reference only; it does not certify evidence validity or readiness. The encrypted cursor binds both authorities and the caller session, expires after 15 minutes, and may become invalid on service restart. Unknown or duplicate query keys are rejected. Responses are no-store.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Header Parameters

Section titled “Header Parameters”
X-Katara-Account-ID
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Required for cookie-authenticated changes. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.

Query Parameters

Section titled “Query Parameters”
source_environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
destination_environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
limit
integer
default: 25 >= 1 <= 25
after
string
>= 1 characters <= 1024 characters

Responses

Section titled “Responses”

200

Section titled “200”

Successful request

Media typeapplication/json

Historical owner-created draft identifiers. evidence_attached means only that a reference is recorded; it never certifies current validity or readiness.

object
source
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
mode
required
Allowed value: test
organization_epoch
required
integer
>= 1 <= 9007199254740991
authority_epoch
required
integer
>= 1 <= 9007199254740991
reset_generation
required
integer
>= 1 <= 9007199254740991
destination
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
mode
required
Allowed value: live
organization_epoch
required
integer
>= 1 <= 9007199254740991
authority_epoch
required
integer
>= 1 <= 9007199254740991
reset_generation
required
integer
>= 1 <= 9007199254740991
data
required
Array<object>
<= 25 items unique items
object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
created_by
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
created_at
required
string format: date-time
evidence_attached
required
boolean
next_cursor
string
>= 1 characters <= 1024 characters /^[A-Za-z0-9_-]+$/
Example
{
  "source": {
    "mode": "test"
  },
  "destination": {
    "mode": "live"
  }
}

Headers

Section titled “Headers”
Cache-Control
string
Allowed value: no-store

409

Section titled “409”

Account_changed: reload and review with the signed-in account.

default

Section titled “default”

Request error

Media typeapplication/json
object
error
required
object
message
required
string
>= 1 characters <= 500 characters
type
required
string
>= 1 characters <= 100 characters
code
required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string
>= 1 characters <= 100 characters
param
required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null
request_id
required
string
>= 1 characters <= 100 characters
upstream_status
required
integer | null
action
Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support
operation_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
snapshot_ref
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
Example
{
  "error": {
    "action": "sign_in"
  }
}