{
    "openapi": "3.1.0",
    "info": {
        "title": "Tier1.shop Client API",
        "version": "1.1.0",
        "description": "Model-neutral API for Tier1.shop clients. Use a revocable account key as a Bearer token. New clients must confirm their mailbox before an account or key is created. Never send payment-card or banking credentials to this API."
    },
    "servers": [
        {
            "url": "https://tier1.shop/wp-json/tier1-api/v1"
        }
    ],
    "externalDocs": {
        "description": "Human-readable API and MCP documentation",
        "url": "https://tier1.shop/api-documentation/"
    },
    "tags": [
        {
            "name": "Discovery",
            "description": "Public machine-readable contracts."
        },
        {
            "name": "Onboarding",
            "description": "Mailbox-confirmed registration and API-key issuance."
        },
        {
            "name": "Account",
            "description": "Owned profile, balances, orders and links."
        },
        {
            "name": "Catalog",
            "description": "Current purchasable tariffs and donor inventory."
        },
        {
            "name": "Drafts",
            "description": "Idempotent draft editing and explicit submission."
        },
        {
            "name": "Checkout",
            "description": "Protected hosted-checkout links. Payment data never enters the API."
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKey": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "t1c_sk_…"
            }
        }
    },
    "paths": {
        "/capabilities": {
            "get": {
                "summary": "API capabilities",
                "security": [],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "operationId": "getCapabilities",
                "tags": [
                    "Discovery"
                ]
            }
        },
        "/openapi.json": {
            "get": {
                "summary": "This OpenAPI document",
                "security": [],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "operationId": "getOpenApi",
                "tags": [
                    "Discovery"
                ]
            }
        },
        "/registration-intents": {
            "post": {
                "summary": "Start verify-first registration",
                "security": [],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "telegram_username": {
                                        "type": "string"
                                    },
                                    "locale": {
                                        "type": "string",
                                        "enum": [
                                            "ru",
                                            "en"
                                        ]
                                    },
                                    "issue_api_key": {
                                        "type": "boolean",
                                        "description": "Show a standard API key once after mailbox confirmation."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Confirmation email accepted"
                    }
                },
                "operationId": "beginRegistration",
                "tags": [
                    "Onboarding"
                ]
            }
        },
        "/registration-intents/{id}": {
            "get": {
                "summary": "Check registration status",
                "security": [],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status_token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "operationId": "checkRegistration",
                "tags": [
                    "Onboarding"
                ]
            }
        },
        "/api-key-requests": {
            "post": {
                "summary": "Request an API key by account email",
                "security": [],
                "responses": {
                    "202": {
                        "description": "Generic accepted response"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100
                                    }
                                }
                            }
                        }
                    }
                },
                "operationId": "requestApiKey",
                "tags": [
                    "Onboarding"
                ]
            }
        },
        "/profile": {
            "get": {
                "summary": "Account profile",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "operationId": "getProfile",
                "tags": [
                    "Account"
                ],
                "x-tier1-scope": "profile:read"
            }
        },
        "/balances": {
            "get": {
                "summary": "RUB/USD wallets and service balances",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "parameters": [
                    {
                        "name": "geo",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "ru",
                                "intl",
                                "all"
                            ],
                            "default": "all"
                        }
                    }
                ],
                "operationId": "getBalances",
                "tags": [
                    "Account"
                ],
                "x-tier1-scope": "balance:read"
            }
        },
        "/orders": {
            "get": {
                "summary": "List owned orders",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "parameters": [
                    {
                        "name": "geo",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "ru",
                                "intl",
                                "all"
                            ],
                            "default": "all"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 50,
                            "default": 20
                        }
                    }
                ],
                "operationId": "listOrders",
                "tags": [
                    "Account"
                ],
                "x-tier1-scope": "orders:read"
            }
        },
        "/orders/{id}": {
            "get": {
                "summary": "Get owned order and links",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "operationId": "getOrder",
                "tags": [
                    "Account"
                ],
                "x-tier1-scope": "orders:read"
            }
        },
        "/links": {
            "get": {
                "summary": "List owned links",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "parameters": [
                    {
                        "name": "geo",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "ru",
                                "intl",
                                "all"
                            ],
                            "default": "all"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "link_type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "yearly",
                                "onetime",
                                "through",
                                "replacement",
                                "renewal_yearly",
                                "renewal_through"
                            ]
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 50,
                            "default": 20
                        }
                    }
                ],
                "operationId": "listLinks",
                "tags": [
                    "Account"
                ],
                "x-tier1-scope": "links:read"
            }
        },
        "/catalog/tariffs": {
            "get": {
                "summary": "Purchasable RU or intl tariffs with exact slot counts",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "parameters": [
                    {
                        "name": "geo",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "ru",
                                "intl"
                            ]
                        }
                    }
                ],
                "operationId": "listTariffs",
                "tags": [
                    "Catalog"
                ],
                "x-tier1-scope": "catalog:read"
            }
        },
        "/catalog/burzh-igaming": {
            "get": {
                "summary": "Anonymized iGaming donors and live slots",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "operationId": "listBurzhIgamingDonors",
                "tags": [
                    "Catalog"
                ],
                "x-tier1-scope": "catalog:read"
            }
        },
        "/links/{id}": {
            "patch": {
                "summary": "Edit a draft link",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 8,
                            "maxLength": 128
                        },
                        "description": "Reuse the same key only when retrying the exact same mutation."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "onetime",
                                            "yearly",
                                            "through"
                                        ]
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "uri"
                                    },
                                    "anchor": {
                                        "type": "string",
                                        "maxLength": 500
                                    },
                                    "context_text": {
                                        "type": "string"
                                    },
                                    "scheduled_at": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "date-time"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "operationId": "updateLinkDraft",
                "tags": [
                    "Drafts"
                ],
                "x-tier1-scope": "links:write"
            },
            "put": {
                "summary": "Edit a draft link",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 8,
                            "maxLength": 128
                        },
                        "description": "Reuse the same key only when retrying the exact same mutation."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "onetime",
                                            "yearly",
                                            "through"
                                        ]
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "uri"
                                    },
                                    "anchor": {
                                        "type": "string",
                                        "maxLength": 500
                                    },
                                    "context_text": {
                                        "type": "string"
                                    },
                                    "scheduled_at": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "date-time"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "operationId": "replaceLinkDraftFields",
                "tags": [
                    "Drafts"
                ],
                "x-tier1-scope": "links:write"
            }
        },
        "/links/{id}/submit": {
            "post": {
                "summary": "Submit one completed link draft",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 8,
                            "maxLength": 128
                        },
                        "description": "Reuse the same key only when retrying the exact same mutation."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "operationId": "submitLink",
                "tags": [
                    "Drafts"
                ],
                "x-tier1-scope": "links:write"
            }
        },
        "/orders/{id}/bulk-update": {
            "post": {
                "summary": "Fill editable order rows without submitting",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 8,
                            "maxLength": 128
                        },
                        "description": "Reuse the same key only when retrying the exact same mutation."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "links": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "type": {
                                                    "type": "string",
                                                    "enum": [
                                                        "onetime",
                                                        "yearly",
                                                        "through"
                                                    ]
                                                },
                                                "url": {
                                                    "type": "string",
                                                    "format": "uri"
                                                },
                                                "anchor": {
                                                    "type": "string",
                                                    "maxLength": 500
                                                },
                                                "context_text": {
                                                    "type": "string"
                                                },
                                                "scheduled_at": {
                                                    "type": [
                                                        "string",
                                                        "null"
                                                    ],
                                                    "format": "date-time"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "operationId": "bulkUpdateOrderDraft",
                "tags": [
                    "Drafts"
                ],
                "x-tier1-scope": "orders:write"
            }
        },
        "/orders/{id}/submit-all": {
            "post": {
                "summary": "Submit every ready row in an order",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 8,
                            "maxLength": 128
                        },
                        "description": "Reuse the same key only when retrying the exact same mutation."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "4XX": {
                        "description": "Validation, authentication or ownership error"
                    }
                },
                "operationId": "submitOrder",
                "tags": [
                    "Drafts"
                ],
                "x-tier1-scope": "orders:write"
            }
        },
        "/checkout-intents": {
            "post": {
                "summary": "Create a protected hosted-checkout link; never accepts card/payment data",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 8,
                            "maxLength": 128
                        },
                        "description": "Reuse the same key only when retrying the exact same mutation."
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "geo",
                                    "items"
                                ],
                                "properties": {
                                    "geo": {
                                        "type": "string",
                                        "enum": [
                                            "ru",
                                            "intl"
                                        ]
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "product_id",
                                                "quantity"
                                            ],
                                            "properties": {
                                                "product_id": {
                                                    "type": "integer"
                                                },
                                                "quantity": {
                                                    "type": "integer",
                                                    "minimum": 1
                                                },
                                                "donor_tokens": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "links": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "type": {
                                                    "type": "string",
                                                    "enum": [
                                                        "onetime",
                                                        "yearly",
                                                        "through"
                                                    ]
                                                },
                                                "url": {
                                                    "type": "string",
                                                    "format": "uri"
                                                },
                                                "anchor": {
                                                    "type": "string",
                                                    "maxLength": 500
                                                },
                                                "context_text": {
                                                    "type": "string"
                                                },
                                                "scheduled_at": {
                                                    "type": [
                                                        "string",
                                                        "null"
                                                    ],
                                                    "format": "date-time"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Protected checkout link created"
                    },
                    "4XX": {
                        "description": "Validation/authentication error"
                    }
                },
                "operationId": "createCheckoutIntent",
                "tags": [
                    "Checkout"
                ],
                "x-tier1-scope": "checkout:create"
            }
        }
    }
}