Export an object’s versions and policy

POST

/katara/v1/orgs/{org_id}/environments/{environment_id}/content/exports

const url = 'https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/content/exports';
const options = {
  method: 'POST',
  headers: {
    'X-Katara-CSRF': '1',
    'Idempotency-Key': '2489E9AD-2EE2-8E00-8EC9-32D5F69181C0',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"content":{"org_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","environment_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","version":1,"integrity":"example","media_type":"text/plain","size_bytes":1}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/content/exports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --header 'X-Katara-CSRF: 1' \
  --data '{ "content": { "org_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "environment_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example", "media_type": "text/plain", "size_bytes": 1 } }'

Requires the configured content service. While the object is live its own policy decides who may export it; once it is deleted that policy is one of the things the deletion removed, so whoever could have deleted it, or an administrator, reads the record instead. The manifest lists every version the object has had, the state each is in, the policy that governed it and how far its deletion has got (reads blocked, derived records removed, stored objects purged) and seals them with a digest taken over the state rather than the moment, so two exports of an unchanged object agree and a manifest kept after the object is gone can still be checked against itself. Exporting is recorded like a change, because a copy of customer content leaving the system is one.

Authorizations

Parameters

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

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

Header Parameters

X-Katara-CSRF

Allowed value: 1

Browser cookie mutations require value 1 and an allowed Origin. Session bearer clients may omit this header.

Idempotency-Key

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

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.

Request Body^required

application/json

object

content

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

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

version

required

integer

>= 1 <= 9223372036854776000

integrity

required

string

/^sha256:[a-f0-9]{64}$/

media_type

required

Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip

size_bytes

required

integer

<= 104857600

Responses

200

Successful request

application/json

object

schema_version

required

integer

>= 1 <= 1

scope

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

content_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

name

The object’s display name. A deleted object has none.

string

>= 1 characters <= 255 characters /^[^\s\x00-\x1f\x7f-\x9f]([^\x00-\x1f\x7f-\x9f]*[^\s\x00-\x1f\x7f-\x9f])?$/

store_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

owner_kind

required

Allowed values: user service

owner_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

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

reset_epoch

required

integer

>= 1 <= 9007199254740991

active_version

required

integer

<= 9007199254740991

access_epoch

required

integer

>= 1 <= 9007199254740991

exported_at

required

string format: date-time

versions

required

Array<object>

<= 1000 items

object

content

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

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

version

required

integer

>= 1 <= 9223372036854776000

integrity

required

string

/^sha256:[a-f0-9]{64}$/

media_type

required

Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip

size_bytes

required

integer

<= 104857600

state

required

Allowed values: uploading candidate approved expired

active

required

boolean

created_at

required

string format: date-time

upload_expires_at

required

string format: date-time

access

required

Array<object>

<= 99 items

object

subject_kind

required

Allowed values: user service team

subject_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

relation

required

Allowed values: reader writer reviewer

digest

required

string

/^sha256:[a-f0-9]{64}$/

deletion

required

object

tombstoned_at

string format: date-time

stages

required

Array<object>

>= 3 items <= 3 items

object

stage

required

Allowed values: reads_blocked derived_records_removed stored_objects_purged

complete

required

boolean

completed_at

string format: date-time

outstanding

required

integer

<= 9007199254740991

elapsed_seconds

required

number

overdue

required

boolean

held

required

boolean

target_seconds

required

integer

>= 1 <= 31536000

cap_seconds

required

integer

>= 1 <= 31536000

record_retained_until

string format: date-time

record_purgeable

required

Whether the deletion record may be destroyed now: its term is up, nothing holds it and the stored objects are gone.

boolean

Example

{
  "owner_kind": "user",
  "versions": [
    {
      "content": {
        "media_type": "text/plain"
      },
      "state": "uploading"
    }
  ],
  "access": [
    {
      "subject_kind": "user",
      "relation": "reader"
    }
  ],
  "deletion": {
    "stages": [
      {
        "stage": "reads_blocked"
      }
    ]
  }
}

409

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

default

Request error

application/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"
  }
}

Export an object’s versions and policy

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

409

default

Example

Request Body^required