{ "openapi": "3.1.0", "info": { "title": "PassportCraft API", "version": "2026-08-01", "description": "Create and publish Digital Product Passports. A credential reaches only the organizations it holds a grant for. The two category endpoints describe the product itself rather than a tenant, and answer without a credential.\n\nForward compatibility. This document describes what /v1 sends today, and we add to it without warning — every object schema is deliberately open. To stay compatible:\n- Ignore response fields you do not recognise, rather than rejecting the response.\n- Treat an unrecognised enum value as a default case, not an error.\n- Treat identifiers as opaque strings; never parse or pattern-match them.\n- Do not depend on the ORDER of fields in a JSON object, or on the exact wording of a human-readable error message. Branch on the machine-readable error code instead.\n- Retry on 429, and on any other refusal that carries a Retry-After header, waiting for the time it names. It is not only a 429 header: a 409 resource_busy, a 503 storage_unavailable and a 503 entitlement_unavailable carry one too, because retrying is their remedy.\n- Retry a 5xx with a NEW Idempotency-Key. A key that recorded a server error replays that error for the retention window — deliberately, because the failure may have been a lost response to a write that SUCCEEDED, and reusing the key is what stops one failed write becoming two.\n- Retry a refused conditional write with a NEW Idempotency-Key. A precondition_failed is recorded against the key that received it and replays for the retention window, so re-reading the passport and retrying under the SAME key returns the original refusal — with the version numbers the FIRST attempt saw. The recording is deliberate: it is what makes a retry after a lost response safe. This applies to the 412 only. A 400 for a malformed header is refused before any key is claimed and is never recorded, so correct the header and retry under the SAME key: your original result is still there.\n- Watch for the Deprecation and Sunset response headers, and for the Link: rel=\"successor-version\" they carry. That is how the removal of an endpoint is announced, and it arrives long before the endpoint stops answering.\n\nTreat every identifier as an opaque string of at most 255 characters. Do not parse them, do not validate their format, and do not assume they are UUIDs — the format may change without notice.\n\nDeprecation. An endpoint scheduled for removal answers with `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers, and a `Link: rel=\"successor-version\"` pointing at its replacement. Watch for them.\n\nThe full compatibility contract, including the enumerated list of changes that would require a new major version, is published at https://passportcraft.com/docs/api/compatibility." }, "servers": [ { "url": "https://passportcraft.com/api/v1" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A secret key, `pc_sk_live_…` or `pc_sk_test_…`. The mode is bound into the credential itself, so a test key cannot reach live passports." } }, "schemas": { "Passport": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "passport" }, "id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "organization_id": { "type": "string", "maxLength": 255 }, "category": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "deactivated", "trashed", "readonly" ] }, "gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "serial_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "livemode": { "type": "boolean" }, "registry_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trashed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "object", "id", "name", "organization_id", "category", "status", "gtin", "serial_number", "external_id", "version", "livemode", "registry_id", "created_at", "updated_at", "published_at", "trashed_at", "data" ], "additionalProperties": {} }, "PassportLinks": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "passport_links" }, "id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "organization_id": { "type": "string", "maxLength": 255 }, "passport": { "type": "string", "maxLength": 255 }, "status": { "type": "string", "enum": [ "draft", "published", "deactivated", "trashed", "readonly" ] }, "livemode": { "type": "boolean" }, "gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "serial_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "public_url": { "type": "string" }, "qr_target": { "type": "string" }, "gs1_digital_link": { "type": "object", "properties": { "uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gtin14": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "serial": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkset_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unavailable_reason": { "anyOf": [ { "type": "string", "enum": [ "gtin_missing", "gtin_invalid" ] }, { "type": "null" } ] } }, "required": [ "uri", "gtin14", "serial", "linkset_url", "unavailable_reason" ], "additionalProperties": {} }, "resolves_publicly": { "type": "boolean" }, "not_resolvable_reason": { "anyOf": [ { "type": "string", "enum": [ "test_mode", "not_published" ] }, { "type": "null" } ] }, "preview_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "id", "name", "organization_id", "passport", "status", "livemode", "gtin", "serial_number", "public_url", "qr_target", "gs1_digital_link", "resolves_publicly", "not_resolvable_reason", "preview_url" ], "additionalProperties": {} }, "Validation": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "validation" }, "id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "organization_id": { "type": "string", "maxLength": 255 }, "passport_id": { "type": "string", "maxLength": 255 }, "category": { "type": "string" }, "schema_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dry_run": { "type": "boolean" }, "valid": { "type": "boolean" }, "publishable": { "type": "boolean" }, "error_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warning_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "checked_at": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "validation_issue" }, "field": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } }, "required": [ "pointer" ], "additionalProperties": {} }, "rule": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "message_key": { "type": "string" }, "message_params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "writable_via_api": { "type": "boolean" } }, "required": [ "object", "field", "source", "rule", "severity", "message", "writable_via_api" ], "additionalProperties": {} } } }, "required": [ "object", "id", "name", "organization_id", "passport_id", "category", "schema_version", "dry_run", "valid", "publishable", "error_count", "warning_count", "checked_at", "issues" ], "additionalProperties": {} }, "Error": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_key", "key_revoked", "key_expired", "key_rotated", "mode_mismatch", "insufficient_scope", "organization_not_found_or_not_granted", "resource_not_found", "wildcard_not_supported", "validation_failed", "invalid_request", "method_not_allowed", "payload_too_large", "unsupported_media_type", "idempotency_conflict", "already_exists", "precondition_failed", "resource_busy", "cursor_invalid", "no_subscription", "plan_required", "payment_overdue", "gtin_required", "wrong_status", "not_trashed", "publish_limit_reached", "unit_limit_reached", "document_missing", "document_feeds_extraction", "delegation_required", "attestation_required", "test_mode_refused", "human_approval_required", "connector_writes_drafts_only", "unit_status_not_allowed", "portal_unavailable", "storage_unavailable", "entitlement_unavailable", "rate_limited", "internal_error", "configuration_error" ] }, "message": { "type": "string" }, "documentation_url": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message", "documentation_url", "request_id" ], "additionalProperties": {} } }, "required": [ "error" ], "additionalProperties": {} }, "List": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": {} }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": {} }, "Credential": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "credential" }, "key_id": { "type": "string" }, "livemode": { "type": "boolean" }, "owner_organization_id": { "type": "string", "maxLength": 255 }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "organization_id": { "type": "string", "maxLength": 255 }, "scopes": { "type": "array", "items": { "type": "string" } }, "granted_at": { "type": "string" } }, "required": [ "organization_id", "scopes", "granted_at" ], "additionalProperties": {} } } }, "required": [ "object", "key_id", "livemode", "owner_organization_id", "expires_at", "last_used_at", "organizations" ], "additionalProperties": {} }, "CategorySchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "category_schema" }, "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "display_name": { "type": "string" }, "schema_version": { "type": "string" }, "field_groups": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "field_group" }, "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "object", "id", "label" ], "additionalProperties": {} } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "field" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "select", "multiselect", "date", "url", "array", "pictogram" ] }, "required": { "type": "boolean" }, "required_when": { "type": "object", "properties": { "field": { "type": "string" }, "one_of": { "type": "array", "items": { "type": "string" } } }, "required": [ "field", "one_of" ], "additionalProperties": {} }, "access_tier": { "type": "string", "enum": [ "public", "restricted", "authority" ] }, "group": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "placeholder": { "type": "string" }, "hint": { "type": "string" }, "help_url": { "type": "string" }, "unit": { "type": "string" }, "unit_field": { "type": "string" }, "default_unit": { "type": "string" }, "min": { "type": "number" }, "max": { "type": "number" }, "item_type": { "type": "string", "const": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": {} } }, "document_types": { "type": "array", "items": { "type": "string", "enum": [ "certification", "image", "document", "conformity_declaration" ] } }, "document_id_key": { "type": "string" }, "requirement": { "type": "string", "enum": [ "required", "recommended", "optional" ] }, "functional_basis": { "type": "string" }, "regulatory_basis": { "type": "array", "items": { "type": "object", "properties": { "regulation": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "in_force", "in_force_conditional", "applies_later", "anticipated", "voluntary" ] }, "jurisdiction": { "type": "string" }, "applies_when": { "type": "string" }, "note": { "type": "string" }, "status_changing": { "type": "boolean" } }, "required": [ "regulation", "reference", "status" ], "additionalProperties": {} } } }, "required": [ "object", "name", "type", "required", "access_tier", "group", "label", "description" ], "additionalProperties": {} } } }, "required": [ "object", "id", "name", "category", "display_name", "schema_version", "field_groups", "fields" ], "additionalProperties": {} }, "Capability": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "capability" }, "id": { "type": "string", "enum": [ "passport_publishing", "france_affichage_filing", "document_upload", "live_api_writes" ] }, "name": { "type": "string" }, "organization_id": { "type": "string", "maxLength": 255 }, "livemode": { "type": "boolean" }, "requested": { "type": "boolean" }, "allowed": { "type": "boolean" }, "verification_status": { "type": "string", "enum": [ "valid", "pending", "invalid", "rejected" ] }, "problems": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_key", "key_revoked", "key_expired", "key_rotated", "mode_mismatch", "insufficient_scope", "organization_not_found_or_not_granted", "resource_not_found", "wildcard_not_supported", "validation_failed", "invalid_request", "method_not_allowed", "payload_too_large", "unsupported_media_type", "idempotency_conflict", "already_exists", "precondition_failed", "resource_busy", "cursor_invalid", "no_subscription", "plan_required", "payment_overdue", "gtin_required", "wrong_status", "not_trashed", "publish_limit_reached", "unit_limit_reached", "document_missing", "document_feeds_extraction", "delegation_required", "attestation_required", "test_mode_refused", "human_approval_required", "connector_writes_drafts_only", "unit_status_not_allowed", "portal_unavailable", "storage_unavailable", "entitlement_unavailable", "rate_limited", "internal_error", "configuration_error" ] }, "message": { "type": "string" }, "type": { "type": "string", "enum": [ "pending", "invalid", "rejected" ] }, "remediating_actions": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "add_subscription", "update_payment_method", "upgrade_plan", "unpublish_a_passport", "complete_france_delegation", "await_portal_verification", "use_live_credential", "delete_unused_documents", "retry" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } } }, "required": [ "code", "message", "type", "remediating_actions" ], "additionalProperties": {} } }, "detail": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "object", "id", "name", "organization_id", "livemode", "requested", "allowed", "verification_status", "problems", "detail" ], "additionalProperties": {} }, "CapabilityList": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": {} }, "UnitList": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Unit" } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": {} }, "PublishApproval": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "publish_approval" }, "id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "organization_id": { "type": "string", "maxLength": 255 }, "passport_id": { "type": "string", "maxLength": 255 }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "superseded" ] }, "review_url": { "type": "string" }, "requested_at": { "type": "string" }, "expires_at": { "type": "string" }, "decided_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "livemode": { "type": "boolean" } }, "required": [ "object", "id", "name", "organization_id", "passport_id", "status", "review_url", "requested_at", "expires_at", "decided_at", "livemode" ], "additionalProperties": {} }, "Affichage": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "affichage" }, "name": { "type": "string" }, "organization_id": { "type": "string", "maxLength": 255 }, "passport_id": { "type": "string", "maxLength": 255 }, "livemode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "not_filed", "draft", "filed", "confirmed", "error" ] }, "filed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "portal_gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "portal_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "filing_available": { "type": "boolean" }, "blockers": { "type": "array", "items": { "type": "string", "enum": [ "test_mode", "delegation_required", "entitlement_unavailable", "plan_required", "gtin_required" ] } }, "delegation_status": { "type": "string", "enum": [ "none", "not_delegated", "pending", "active" ] } }, "required": [ "object", "name", "organization_id", "passport_id", "livemode", "status", "filed_at", "portal_gtin", "portal_score", "filing_available", "blockers", "delegation_status" ], "additionalProperties": {} }, "AffichageFiling": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "affichage" }, "name": { "type": "string" }, "organization_id": { "type": "string", "maxLength": 255 }, "passport_id": { "type": "string", "maxLength": 255 }, "livemode": { "type": "boolean" }, "changed": { "type": "boolean" }, "unchanged_reason": { "anyOf": [ { "type": "string", "enum": [ "score_unchanged" ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "not_filed", "draft", "filed", "confirmed", "error" ] }, "filed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "portal_gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "portal_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "standardized_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durability": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "official_label_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ecobalyse_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "declared_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "free_offer": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "filed_readback_failed" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } } }, "required": [ "object", "name", "organization_id", "passport_id", "livemode", "changed", "unchanged_reason", "status", "filed_at", "portal_gtin", "portal_score", "standardized_score", "durability", "official_label_url", "ecobalyse_version", "declared_score", "free_offer" ], "additionalProperties": {} }, "Unit": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "unit" }, "id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "organization_id": { "type": "string", "maxLength": 255 }, "passport_id": { "type": "string", "maxLength": 255 }, "passport": { "type": "string", "maxLength": 255 }, "unit_serial": { "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "object", "id", "name", "organization_id", "passport_id", "passport", "unit_serial", "status", "livemode", "created_at" ], "additionalProperties": {} }, "Document": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "document" }, "id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "organization_id": { "type": "string", "maxLength": 255 }, "passport_id": { "type": "string", "maxLength": 255 }, "passport": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "certification", "image", "document", "conformity_declaration" ] }, "access_tier": { "type": "string", "enum": [ "public", "restricted", "authority" ] }, "file_name": { "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file_size": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "upload_state": { "type": "string", "enum": [ "pending", "ready", "unknown" ] }, "uploaded_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "created_at": { "type": "string" }, "linked_at": { "type": "string" }, "upload": { "type": "object", "properties": { "url": { "type": "string" }, "method": { "type": "string", "const": "PUT" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "max_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url", "method", "headers", "expires_at", "max_bytes" ], "additionalProperties": {} } }, "required": [ "object", "id", "name", "organization_id", "passport_id", "passport", "type", "access_tier", "file_name", "display_name", "mime_type", "file_size", "upload_state", "uploaded_at", "livemode", "created_at", "linked_at" ], "additionalProperties": {} }, "DocumentDeletion": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "document.deleted" }, "id": { "type": "string", "maxLength": 255 }, "organization_id": { "type": "string", "maxLength": 255 }, "passport_id": { "type": "string", "maxLength": 255 }, "livemode": { "type": "boolean" }, "detached": { "type": "boolean" }, "deleted_from_library": { "type": "boolean" }, "remaining_links": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "document_limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "object", "id", "organization_id", "passport_id", "livemode", "detached", "deleted_from_library", "remaining_links" ], "additionalProperties": {} }, "ImportJob": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "import_job" }, "id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "organization_id": { "type": "string", "maxLength": 255 }, "livemode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] }, "total_rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "succeeded_rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed_rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pending_rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attempts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "type": "string" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "id", "name", "organization_id", "livemode", "status", "total_rows", "succeeded_rows", "failed_rows", "pending_rows", "attempts", "created_at", "started_at", "completed_at" ], "additionalProperties": {} }, "ImportRow": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "import_row" }, "row_index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "passport_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "passport_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "detail": {} }, "required": [ "code", "detail" ], "additionalProperties": {} }, { "type": "null" } ] }, "processed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "row_index", "external_id", "status", "passport_id", "passport_name", "error", "processed_at" ], "additionalProperties": {} }, "ImportJobWithRows": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "import_job" }, "id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "organization_id": { "type": "string", "maxLength": 255 }, "livemode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] }, "total_rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "succeeded_rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed_rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pending_rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attempts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "type": "string" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rows": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImportRow" } }, "has_more": { "type": "boolean" }, "next_after_row_index": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_after_row_index" ], "additionalProperties": {} } }, "required": [ "object", "id", "name", "organization_id", "livemode", "status", "total_rows", "succeeded_rows", "failed_rows", "pending_rows", "attempts", "created_at", "started_at", "completed_at", "rows" ], "additionalProperties": {} } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/whoami": { "get": { "operationId": "getWhoami", "summary": "Describe the calling credential.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/categories": { "get": { "operationId": "listCategories", "summary": "List product categories.", "security": [ {}, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/categories/{category}/schema": { "get": { "operationId": "getCategorySchema", "summary": "Fetch a category field schema.", "security": [ {}, { "bearerAuth": [] } ], "parameters": [ { "name": "category", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategorySchema" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations": { "get": { "operationId": "listOrganizations", "summary": "List organizations this credential can act for.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Describe what this credential may do for this organization.", "security": [ { "bearerAuth": [ "passports:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityList" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/events": { "get": { "operationId": "listEvents", "summary": "Read the organization event feed.", "description": "Events are returned OLDEST first, so a stored `cursor` reads forward from where you stopped. It is the only cursor-paginated collection here that is not newest-first, and that is what makes exactly-once sequential replay possible. To reach the most recent events on a feed you have never read, page to the end once and keep the final `next_cursor`. Once you have sent a cursor it is re-issued even on an empty page, which is the normal steady state of a caught-up poller; a first call that returns no events at all has no position to re-issue and answers `next_cursor: null`.", "security": [ { "bearerAuth": [ "events:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "limit", "in": "query", "required": false, "description": "How many records to return. The server may return fewer.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` from the previous page. The feed is OLDEST first, so this reads forward into events you have not seen yet. A cursor encodes the filters it was issued under; sending it with different filters is refused with `cursor_invalid`.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Repeat to filter on more than one event type. Omit for every type.", "explode": true, "style": "form", "schema": { "type": "array", "items": { "type": "string", "enum": [ "passport.created", "passport.updated", "passport.published", "passport.unpublished", "passport.deactivated", "passport.trashed", "passport.restored", "passport.deleted", "publish_approval.requested", "publish_approval.approved", "publish_approval.rejected", "publish_approval.expired", "publish_approval.superseded" ] } } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "The request could not be understood. Codes: cursor_invalid, invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/passports": { "get": { "operationId": "listPassports", "summary": "List passports.", "security": [ { "bearerAuth": [ "passports:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "limit", "in": "query", "required": false, "description": "How many records to return. The server may return fewer.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` from the previous page. A cursor encodes the filters it was issued under; sending it with different filters is refused with `cursor_invalid`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Return only passports in this status.", "schema": { "type": "string", "enum": [ "draft", "published", "deactivated", "trashed" ] } }, { "name": "category", "in": "query", "required": false, "description": "Return only passports in this category.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "An RFC 3339 timestamp. Returns passports updated at or after it, which is how an integrator polls for changes without re-reading the catalogue.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "The request could not be understood. Codes: cursor_invalid, invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createPassport", "summary": "Create a passport.", "security": [ { "bearerAuth": [ "passports:write" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays a completed response rather than repeating the effect. Scoped to the organization, so two tenants cannot collide on the same key. A key is remembered for 30 days; after that it is forgotten entirely and a retry carrying it EXECUTES AGAIN rather than replaying.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "description": "A category id from GET /categories. It fixes the field schema and cannot be changed afterwards." }, "external_id": { "type": [ "string", "null" ], "description": "Your own identifier for this product, 1 to 255 characters. Unique within the organization and the mode, which is what lets you reconcile without storing our ids — so the same id can exist once in test and once in live." }, "data": { "type": "object", "description": "The passport document. Keys are field names from the category schema, plus each documentable field's `document_id_key` companion; anything else is refused rather than silently stored.", "additionalProperties": true } }, "required": [ "category" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passport" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan or the billing state does not allow this request. Codes: no_subscription, payment_overdue, plan_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current state of the resource, or with an earlier use of this Idempotency-Key. Codes: already_exists, idempotency_conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The request body was not sent as application/json. Codes: unsupported_media_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused on its content. Codes: validation_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/publish-approvals/{id}": { "get": { "operationId": "getPublishApproval", "summary": "Fetch one publish approval.", "description": "The outcome of a publish our agent connector requested. A connector credential cannot publish: `POST …/passports/{id}/publish` answers 202 with an `approval_id`, and a person at the brand decides it. Poll this, or subscribe to the `publish_approval.*` events on the change feed. Approvals expire seven days after they are requested, and the transition lands on the first call that acts on a pending row past its deadline: this endpoint, or a later publish request from a connector for the same passport, which closes the lapsed one before it opens a new one. Rendering the approval list a person sees does not land it: that view hides anything past its deadline without writing. If a person publishes the passport before anything closes a lapsed request, their decision is what that request records, whether or not its deadline had passed.", "security": [ { "bearerAuth": [ "passports:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishApproval" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/passports/{id}": { "get": { "operationId": "getPassport", "summary": "Fetch one passport.", "security": [ { "bearerAuth": [ "passports:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The passport version as an entity-tag. It may arrive weak-prefixed (`W/\"5\"`) because our CDN can weaken it when it compresses, so do not parse it by stripping quotes — read the `version` field from the response body instead, and send that integer back as `Expected-Version` on a PATCH. A tagged `If-Match` is refused where we read it — the passport PATCH and the document DELETE — because our CDN rewrites the response it is compared against. This GET does not read the header.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passport" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updatePassport", "summary": "Apply a JSON Merge Patch to a passport.", "security": [ { "bearerAuth": [ "passports:write" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "Expected-Version", "in": "header", "required": false, "description": "The `version` of the passport you read, as an integer. The write is refused with `precondition_failed` if the passport changed in between, which is the only way to make a read-modify-write safe against a concurrent editor. Use this rather than `If-Match`. Retry a refused write with a NEW `Idempotency-Key`: the refusal is recorded against the old one and would be replayed.", "schema": { "type": "integer", "minimum": 0, "maximum": 999999999999999 } }, { "name": "If-Match", "in": "header", "required": false, "description": "REFUSED with `invalid_request` unless it is exactly `*` — in particular whenever it carries an entity-tag. Our CDN compares `If-Match` against the RESPONSE and rewrites the result, so a conditional write would commit and still be reported to you as 412 — refusing it is what stops that. Send the version as `Expected-Version` instead. `If-Match: *`, which asks only that the passport still exist, is accepted.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays a completed response rather than repeating the effect. Scoped to the organization, so two tenants cannot collide on the same key. A key is remembered for 30 days; after that it is forgotten entirely and a retry carrying it EXECUTES AGAIN rather than replaying.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "An RFC 7386 JSON Merge Patch applied to the passport document. Omit a key to leave it alone; send null to delete it. Arrays are replaced, never merged.", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passport" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan or the billing state does not allow this request. Codes: no_subscription, payment_overdue, plan_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current state of the resource, or with an earlier use of this Idempotency-Key. Codes: idempotency_conflict, wrong_status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The passport changed — either since the version supplied in Expected-Version, or while the request was in flight. Codes: precondition_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The request body was not sent as application/json. Codes: unsupported_media_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused on its content. Codes: validation_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/passports/{id}/publish": { "post": { "operationId": "publishPassport", "summary": "Publish a passport.", "security": [ { "bearerAuth": [ "passports:write" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays a completed response rather than repeating the effect. Scoped to the organization, so two tenants cannot collide on the same key. A key is remembered for 30 days; after that it is forgotten entirely and a retry carrying it EXECUTES AGAIN rather than replaying.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passport" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan or the billing state does not allow this request. Codes: no_subscription, payment_overdue, plan_required, publish_limit_reached, unit_limit_reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current state of the resource, or with an earlier use of this Idempotency-Key. Codes: idempotency_conflict, wrong_status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The request body was not sent as application/json. Codes: unsupported_media_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused on its content. Codes: document_missing, gtin_required, validation_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency of OURS did not answer, so the request was not carried out. Nothing changed, and retrying after the Retry-After delay is the remedy. Codes: storage_unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/passports/{id}/unpublish": { "post": { "operationId": "unpublishPassport", "summary": "Unpublish a passport.", "security": [ { "bearerAuth": [ "passports:write" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays a completed response rather than repeating the effect. Scoped to the organization, so two tenants cannot collide on the same key. A key is remembered for 30 days; after that it is forgotten entirely and a retry carrying it EXECUTES AGAIN rather than replaying.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passport" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan or the billing state does not allow this request. Codes: no_subscription, payment_overdue, plan_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current state of the resource, or with an earlier use of this Idempotency-Key. Codes: idempotency_conflict, wrong_status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The passport changed — either since the version supplied in Expected-Version, or while the request was in flight. Codes: precondition_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The request body was not sent as application/json. Codes: unsupported_media_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused on its content. Codes: validation_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-destructive": true, "description": "Charges the destructive-transition cap in addition to the request rate limit. The cap exists because a loop of cheap, well-formed requests can take an entire catalogue dark without ever approaching a per-minute ceiling." } }, "/organizations/{organization}/passports/{id}/trash": { "post": { "operationId": "trashPassport", "summary": "Move a passport to trash.", "security": [ { "bearerAuth": [ "passports:write" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays a completed response rather than repeating the effect. Scoped to the organization, so two tenants cannot collide on the same key. A key is remembered for 30 days; after that it is forgotten entirely and a retry carrying it EXECUTES AGAIN rather than replaying.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passport" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan or the billing state does not allow this request. Codes: no_subscription, payment_overdue, plan_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current state of the resource, or with an earlier use of this Idempotency-Key. Codes: idempotency_conflict, wrong_status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The passport changed — either since the version supplied in Expected-Version, or while the request was in flight. Codes: precondition_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The request body was not sent as application/json. Codes: unsupported_media_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused on its content. Codes: validation_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-destructive": true, "description": "Charges the destructive-transition cap in addition to the request rate limit. The cap exists because a loop of cheap, well-formed requests can take an entire catalogue dark without ever approaching a per-minute ceiling." } }, "/organizations/{organization}/passports/{id}/restore": { "post": { "operationId": "restorePassport", "summary": "Restore a passport from trash.", "security": [ { "bearerAuth": [ "passports:write" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays a completed response rather than repeating the effect. Scoped to the organization, so two tenants cannot collide on the same key. A key is remembered for 30 days; after that it is forgotten entirely and a retry carrying it EXECUTES AGAIN rather than replaying.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passport" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan or the billing state does not allow this request. Codes: no_subscription, payment_overdue, plan_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current state of the resource, or with an earlier use of this Idempotency-Key. Codes: idempotency_conflict, not_trashed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The passport changed — either since the version supplied in Expected-Version, or while the request was in flight. Codes: precondition_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The request body was not sent as application/json. Codes: unsupported_media_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused on its content. Codes: validation_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/passports/{id}/validate": { "post": { "operationId": "validatePassport", "summary": "Check a passport against its category schema without saving.", "security": [ { "bearerAuth": [ "passports:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Fields to merge in before checking, so you can test an edit without saving it. Nothing is written either way.", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Validation" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The request body was not sent as application/json. Codes: unsupported_media_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused on its content. Codes: validation_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency of OURS did not answer, so the request was not carried out. Nothing changed, and retrying after the Retry-After delay is the remedy. Codes: storage_unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/passports/{id}/links": { "get": { "operationId": "getPassportLinks", "summary": "Fetch the public and GS1 Digital Link URLs.", "security": [ { "bearerAuth": [ "passports:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportLinks" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/passports/{id}/affichage": { "get": { "operationId": "getAffichage", "summary": "Read the French affichage environnemental state.", "security": [ { "bearerAuth": [ "passports:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Affichage" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "fileAffichage", "summary": "File the French affichage environnemental declaration.", "security": [ { "bearerAuth": [ "filings:write" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays a completed response rather than repeating the effect. Scoped to the organization, so two tenants cannot collide on the same key. A key is remembered for 30 days; after that it is forgotten entirely and a retry carrying it EXECUTES AGAIN rather than replaying.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AffichageFiling" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan or the billing state does not allow this request. Codes: no_subscription, payment_overdue, plan_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: attestation_required, delegation_required, insufficient_scope, test_mode_refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current state of the resource, or with an earlier use of this Idempotency-Key. Codes: idempotency_conflict, wrong_status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The request body was not sent as application/json. Codes: unsupported_media_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused on its content. Codes: gtin_required, validation_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "A government portal this operation depends on did not answer. Nothing was filed. Codes: portal_unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency of OURS did not answer, so the request was not carried out. Nothing changed, and retrying after the Retry-After delay is the remedy. Codes: entitlement_unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/passports/{id}/units": { "get": { "operationId": "listUnits", "summary": "List serialized units.", "security": [ { "bearerAuth": [ "units:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "limit", "in": "query", "required": false, "description": "How many records to return. The server may return fewer.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` from the previous page. A cursor encodes the filters it was issued under; sending it with different filters is refused with `cursor_invalid`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Return only units in this status.", "schema": { "type": "string" } }, { "name": "unit_serial", "in": "query", "required": false, "description": "Return the single unit carrying this serial.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "The request could not be understood. Codes: cursor_invalid, invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createUnits", "summary": "Create serialized units.", "security": [ { "bearerAuth": [ "units:write" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays a completed response rather than repeating the effect. Scoped to the organization, so two tenants cannot collide on the same key. A key is remembered for 30 days; after that it is forgotten entirely and a retry carrying it EXECUTES AGAIN rather than replaying.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "units": { "type": "array", "description": "Between 1 and 1000 units. The parent passport must be in the `battery` category — serialized units are a battery concept, and any other parent is refused with `invalid_request`. A serial repeated inside one request is refused per row rather than deduplicated, so a bulk importer never believes it created a row it did not.", "items": { "type": "object", "properties": { "unit_serial": { "type": "string", "description": "The serial carried by this physical item, up to 70 characters. Unique within the passport." }, "status": { "type": [ "string", "null" ], "description": "The lifecycle state, from the Annex XIII vocabulary: original, repurposed, re-used, remanufactured, waste. Stored as free text up to 70 characters — a value outside that list is accepted and then recognised by nothing." } }, "required": [ "unit_serial" ] } } }, "required": [ "units" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnitList" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan or the billing state does not allow this request. Codes: no_subscription, payment_overdue, plan_required, unit_limit_reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current state of the resource, or with an earlier use of this Idempotency-Key. Codes: already_exists, idempotency_conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The request body was not sent as application/json. Codes: unsupported_media_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused on its content. Codes: validation_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/documents": { "get": { "operationId": "listLibraryDocuments", "summary": "List every document in the workspace library.", "security": [ { "bearerAuth": [ "documents:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "limit", "in": "query", "required": false, "description": "How many records to return. The server may return fewer.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` from the previous page. A cursor encodes the filters it was issued under; sending it with different filters is refused with `cursor_invalid`.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Return only documents of this type.", "schema": { "type": "string", "enum": [ "certification", "image", "document", "conformity_declaration" ] } }, { "name": "access_tier", "in": "query", "required": false, "description": "Return only documents published to this audience tier.", "schema": { "type": "string", "enum": [ "public", "restricted", "authority" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "The request could not be understood. Codes: cursor_invalid, invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/passports/{id}/documents": { "get": { "operationId": "listDocuments", "summary": "List documents linked to a passport.", "security": [ { "bearerAuth": [ "documents:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "limit", "in": "query", "required": false, "description": "How many records to return. The server may return fewer.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` from the previous page. A cursor encodes the filters it was issued under; sending it with different filters is refused with `cursor_invalid`.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Return only documents of this type.", "schema": { "type": "string", "enum": [ "certification", "image", "document", "conformity_declaration" ] } }, { "name": "access_tier", "in": "query", "required": false, "description": "Return only documents published to this audience tier.", "schema": { "type": "string", "enum": [ "public", "restricted", "authority" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "The request could not be understood. Codes: cursor_invalid, invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createDocument", "summary": "Create a document and get a signed upload URL.", "security": [ { "bearerAuth": [ "documents:write" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays a completed response rather than repeating the effect. Scoped to the organization, so two tenants cannot collide on the same key. A key is remembered for 30 days; after that it is forgotten entirely and a retry carrying it EXECUTES AGAIN rather than replaying.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "link", "type": "object", "properties": { "document_id": { "type": "string", "description": "Link a document already in the organization library instead of uploading. Cannot be combined with any of the upload fields. Linking a document not yet attached answers 201; re-linking one already attached answers 200. Neither carries an `upload` object." } }, "required": [ "document_id" ], "not": { "anyOf": [ { "properties": { "type": {} }, "required": [ "type" ] }, { "properties": { "access_tier": {} }, "required": [ "access_tier" ] }, { "properties": { "file_name": {} }, "required": [ "file_name" ] }, { "properties": { "mime_type": {} }, "required": [ "mime_type" ] }, { "properties": { "file_size": {} }, "required": [ "file_size" ] }, { "properties": { "display_name": {} }, "required": [ "display_name" ] } ] } }, { "title": "upload", "type": "object", "properties": { "type": { "type": "string", "description": "Required when uploading; must be absent when `document_id` is set. One of certification, image, document, conformity_declaration. An `image` uploaded with `access_tier: public` is shown as the product photo on the published passport page, and several render as a gallery. This API cannot choose which of them is the primary photo — a person sets that in the passport editor, under the product photos. No category schema declares an image field, so uploading is the only way to give a passport a photo.", "enum": [ "certification", "image", "document", "conformity_declaration" ] }, "access_tier": { "type": "string", "description": "Required when uploading; must be absent when `document_id` is set. One of public, restricted, authority. It decides who can read the file once the passport is live.", "enum": [ "public", "restricted", "authority" ] }, "file_name": { "type": "string", "description": "Required when uploading; must be absent when `document_id` is set. The file name to store it under." }, "mime_type": { "type": "string", "description": "Required when uploading; must be absent when `document_id` is set. One of application/pdf, image/png, image/jpeg, image/webp. Sent verbatim to storage, which refuses a mismatch.", "enum": [ "application/pdf", "image/png", "image/jpeg", "image/webp" ] }, "file_size": { "type": [ "integer", "null" ], "description": "Size in bytes, up to 10485760." }, "display_name": { "type": [ "string", "null" ], "description": "The label a reader sees. Defaults to file_name." } }, "required": [ "type", "access_tier", "file_name", "mime_type" ], "not": { "anyOf": [ { "properties": { "document_id": {} }, "required": [ "document_id" ] } ] } } ] } } } }, "responses": { "200": { "description": "The document named by `document_id` was already attached to this passport. Nothing changed and no `upload` object is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan or the billing state does not allow this request. Codes: no_subscription, payment_overdue, plan_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current state of the resource, or with an earlier use of this Idempotency-Key. Codes: idempotency_conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The request body was not sent as application/json. Codes: unsupported_media_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused on its content. Codes: validation_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/passports/{id}/documents/{documentId}": { "delete": { "operationId": "deleteDocument", "summary": "Detach a document, and delete it from the library when nothing else holds it.", "security": [ { "bearerAuth": [ "documents:write" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "If-Match", "in": "header", "required": false, "description": "REFUSED with `invalid_request` unless it is exactly `*`. This endpoint has no conditional form. DELETE is the one method we have not measured against our CDN, which on some paths compares `If-Match` against the RESPONSE and rewrites a success into a 412 — and a detach that has already committed must never be reported to you as a refusal. `If-Match: *`, which asks only that the document still exist, is accepted.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDeletion" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan or the billing state does not allow this request. Codes: no_subscription, payment_overdue, plan_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current state of the resource, or with an earlier use of this Idempotency-Key. Codes: document_feeds_extraction, resource_busy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/imports": { "post": { "operationId": "createImport", "summary": "Start an asynchronous bulk import.", "security": [ { "bearerAuth": [ "passports:write" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays a completed response rather than repeating the effect. Scoped to the organization, so two tenants cannot collide on the same key. A key is remembered for 30 days; after that it is forgotten entirely and a retry carrying it EXECUTES AGAIN rather than replaying.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "description": "Between 1 and 500 rows. Exceeding the ceiling is refused with its own `max_rows` rule, which is the refusal a batching loop branches on. An unrecognised key anywhere in a row is an error, not a silently dropped field.", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "A category id from GET /categories." }, "data": { "type": "object", "description": "The passport document, exactly as POST /passports takes it.", "additionalProperties": true }, "external_id": { "type": "string", "description": "Your identifier for the row. Echoed back on the per-row result, which is how a failed row is reconciled." } }, "required": [ "category", "data" ] } } }, "required": [ "rows" ] } } } }, "responses": { "202": { "description": "Accepted. The work has not run yet.", "headers": { "Location": { "description": "The import job to poll for progress and per-row results.", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan or the billing state does not allow this request. Codes: no_subscription, payment_overdue, plan_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current state of the resource, or with an earlier use of this Idempotency-Key. Codes: idempotency_conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The request body was not sent as application/json. Codes: unsupported_media_type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused on its content. Codes: validation_failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listImports", "summary": "List import jobs.", "security": [ { "bearerAuth": [ "passports:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "limit", "in": "query", "required": false, "description": "How many records to return. The server may return fewer.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` from the previous page. A cursor encodes the filters it was issued under; sending it with different filters is refused with `cursor_invalid`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Return only jobs in this status.", "schema": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "The request could not be understood. Codes: cursor_invalid, invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{organization}/imports/{id}": { "get": { "operationId": "getImport", "summary": "Fetch one import job and its progress.", "security": [ { "bearerAuth": [ "passports:read" ] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "row_limit", "in": "query", "required": false, "description": "How many per-row results to include with the job.", "schema": { "type": "integer" } }, { "name": "after_row_index", "in": "query", "required": false, "description": "Return per-row results after this row index, so a large job can be walked.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobWithRows" } } } }, "400": { "description": "The request could not be understood. Codes: invalid_request, mode_mismatch, wildcard_not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential. Codes: invalid_key, key_expired, key_revoked, key_rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the required scope. Codes: insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another tenant, or it is in the other mode. Codes: organization_not_found_or_not_granted, resource_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this endpoint accepts. Codes: payload_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited, or the destructive-transition cap was reached. Codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Codes: configuration_error, internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }