> For the complete documentation index, see [llms.txt](https://project-03b42162.restlessdocs.com/llms.txt).

# Get one file or folder, with its path and whether it is protected

`GET https://tarkle.com/api/v1/files/{id}`

OpenAPI definition for a single operation of the Tarkle API - parameters, request body, and response schemas.

```yaml
openapi: 3.1.0
info:
  title: Tarkle API
  version: v1
  summary: Brands, files, uploads and storage usage for Tarkle workspaces
  description: >-
    Public API for Tarkle workspaces: brands, files and folders, uploads, storage usage and the
    workspaces a token can reach.


    **Start.** Create a token in Settings > API and send it as `Authorization: Bearer tk_...`. A
    token works for every workspace its creator can use. Call GET /workspaces to list them, then
    send the workspace's 8-character key in the `X-Workspace-Key` header (or the `workspace_key`
    query parameter) on every other call.


    **Scopes.** `brands:read` (Read brands, their assets, brand.md and analytics); `brands:write`
    (Update a brand's text, links, access and settings); `brands:create` (Create brands, delete them
    to the bin and restore them from it); `brands:domains` (Connect, check and remove a brand's
    custom domain); `brands:files` (Upload a brand's icon, logos, banner, social image, favicon and
    collection files); `brands:requests` (List download and view requests and approve or reject
    them); `webhooks:manage` (Add, change and remove webhook endpoints, send test events and read
    the delivery log); `files:read` (List and download files and folders); `files:write` (Create
    folders, rename and delete files and folders (and restore them from the bin); uploads are
    separate endpoints); `ai:ask` (Ask a question about the library's files and get an answer with
    sources; it spends AI credits like a question in Ask about files (read-only));
    `transfers:create` (Create a shareable transfer link from files or folders already in the
    library, deliver it to contacts' client portals, change it (view only, expiry, password) and
    delete it); `transfers:read` (Read a transfer's status); `contacts:create` (Add a contact to the
    workspace); `contacts:read` (List and search the workspace's contacts, and read their portal
    upload use); `contacts:portal` (Turn a contact's client portal access on or off, resend their
    sign-in email and set their portal upload limit); `file_requests:create` (Create a public upload
    link (a file request)); `file_requests:read` (List the workspace's file requests);
    `teams:create` (Create a team folder (Pro only, owner or admin)). Each operation lists the scope
    it needs in `x-required-scope` and in its `security` requirement. Every API key made in Settings
    > API holds every scope and is limited only by the workspaces it may reach; there is no OAuth
    flow for this API (the OAuth login of the MCP server does not issue tokens for it), so no oauth2
    scheme is declared.


    **Limits.** Three limits follow the organization's plan (Free, Pro, Agency). Per API key: 50 /
    250 / 500 requests a minute, and 5 / 25 / 50 search and AI requests a minute (GET /files/search,
    POST /brand-lookup, POST /ai/ask; they also count in the first limit). Per organization, shared
    by all its keys and workspaces: 2,500 / 25,000 / 100,000 requests a day (resets at midnight
    UTC); a request costs 1, a search 5. Reseller has the Agency numbers and Reseller Pro double
    them (1,000 and 100 a minute per key, 200,000 a day); a lifetime plan gets half of its plan's
    per-minute and daily numbers. Read the numbers from the headers instead of hard-coding them.
    Every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
    `X-RateLimit-Reset` (Unix seconds) for the minute, the IETF forms `RateLimit-Limit`,
    `RateLimit-Remaining`, `RateLimit-Reset` (seconds left) and `RateLimit-Policy` (for example
    250;w=60, 25000;w=86400), and `X-Quota-Limit`, `X-Quota-Remaining` and `X-Quota-Reset` (Unix
    seconds) for the day. From 80% of the day `X-Quota-Warning: 80%` is added. A 429 adds
    `Retry-After` (seconds): code `rate_limited` when a per-minute limit was hit, code
    `quota_exceeded` when the day is used up (wait until midnight UTC). A refused request costs no
    quota. A 401 and this document carry the minute headers for the caller's IP bucket (60 a
    minute), which only reports and refuses nothing. Keys made before 2026-11-15 keep the earlier
    limits (120 a minute on brand operations, 600 on files operations, no daily quota refusal) until
    2026-12-13.


    **Errors.** Every error is a problem details object (RFC 9457) with the content type
    `application/problem+json`: `type`, `title`, `status`, `detail` and a stable `code` to branch
    on. The older `error: { code, message }` envelope is still included. `x-error-codes` lists every
    code with its status and meaning.


    **Safe repeats.** Send `Idempotency-Key` (any random value up to 255 characters) with a POST,
    PATCH, PUT or DELETE and a repeat of the same request returns the first answer instead of doing
    it twice. See the header's description for the rules.


    **Versioning.** The version is in the path (`/api/v1`). Inside v1 we only add things: endpoints,
    optional parameters, response fields and error codes, so ignore fields and codes you do not
    know. A change that could break a client ships as a new version, and the old one keeps working
    for at least 6 months after we announce its end, with `Deprecation` (RFC 9745) and `Sunset` (RFC
    8594) headers, plus a `Link` with rel deprecation or sunset, on its responses during that time.
    No version is deprecated today, so those headers do not appear yet (see `x-api-lifecycle`).


    Guides and examples: https://tarkle.com/docs/api/brands
  termsOfService: https://tarkle.com/terms
  contact:
    name: Tarkle support
    email: support@tarkle.tech
    url: https://tarkle.com/contact
externalDocs:
  description: Tarkle API guides
  url: https://tarkle.com/docs/api/brands
servers:
  - url: https://tarkle.com/api/v1
tags:
  - name: Brands
    description: >-
      Read and update brand pages, their assets, brand.md and analytics. The token's creator must be
      an owner or admin of the workspace.
  - name: Requests
    description: Download and view requests people send from a brand page, and your decision on them.
  - name: Webhooks
    description: >-
      Tarkle sends signed events to addresses you register. Each delivery is a POST of the
      WebhookEvent object with the headers Tarkle-Signature (t=<unix seconds>,v1=<hex HMAC-SHA256 of
      "<t>.<raw body>" with your endpoint's secret>, one v1 per secret in force), Tarkle-Event,
      Tarkle-Event-Id and Tarkle-Delivery. Check the signature on the raw body and reject a
      timestamp more than 5 minutes old. Events: brand.viewed (only when an endpoint names it; "all
      events" does not include page views), brand.downloaded (the file, never the visitor),
      brand.updated (the names of what changed), brand.request.created, brand.request.approved and
      brand.request.rejected (who asked: name, company, email). Answer with any 2xx within 10
      seconds. Otherwise Tarkle retries up to 8 times over about 24 hours; an endpoint that keeps
      failing is switched off and the owner is emailed. Redirects are not followed and addresses on
      private networks are refused. The token's creator must be an owner or admin of the workspace.
  - name: Files
    description: >-
      The workspace library: list, read, download, create folders, rename, move, copy, delete and
      restore; uploads, including multipart; storage usage; and the workspaces a token can act on.
  - name: Transfers
    description: >-
      Shareable links from files or folders already in the library -- a plain file transfer, the
      same kind the app's own send flow creates. No video, audio or canvas transfers, no payment and
      no recipient emails through this endpoint; create one, read its status, or delete it early.
  - name: Galleries
    description: >-
      A folder of photos shared as a gallery: free, or paid with watermarked previews and a checkout
      link (pay_url) the buyer pays through with PayPal or card, whichever the workspace connected.
      Getting paid needs Pro and PayPal or Stripe connected in Settings > Integrations.
  - name: Contacts
    description: >-
      The workspace's clients (customers you share files with). Add one, list and search existing
      contacts, and turn client portal access on or off. Organizations are created as a side effect
      of adding a contact with an organization name.
  - name: File requests
    description: >-
      A public upload link that collects files from anyone who opens it. Create one, or list
      existing requests.
  - name: Teams
    description: >-
      Team folders: Pro-only shared folders with their own storage budget. Only an owner or admin
      may create one.
components:
  schemas:
    Problem:
      type: object
      description: >-
        A problem details object (RFC 9457), sent as application/problem+json on every error. Branch
        on code, not on detail: code is stable, detail is for people and can change.
      properties:
        type:
          type: string
          format: uri
          description: >-
            Identifies the problem: https://tarkle.com/docs/api/errors/<code>. Treat it as an
            identifier
        title:
          type: string
          description: A short, fixed summary of the problem type
        status:
          type: integer
          description: The HTTP status code, repeated for clients that lose the response line
        detail:
          type: string
          description: What went wrong this time, in plain words
        code:
          type: string
          description: >-
            A stable machine-readable code such as not_found or name_taken. Every code is listed in
            x-error-codes. v1 can add codes, so treat one you do not know by its HTTP status
        details:
          type: object
          additionalProperties: true
          description: Extra members for some codes; x-details-by-code says which schema each uses
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
          required:
            - code
            - message
          description: >-
            The envelope older clients read: the same code, with detail as message. Prefer the
            top-level members
      required:
        - type
        - title
        - status
        - detail
        - code
        - error
      x-details-by-code:
        conflict:
          $ref: '#/components/schemas/ConflictDetails'
        empty_version_not_supported:
          $ref: '#/components/schemas/ChoicesDetails'
        incomplete:
          $ref: '#/components/schemas/IncompleteDetails'
        transfer_active:
          $ref: '#/components/schemas/TransferActiveDetails'
        protected:
          $ref: '#/components/schemas/ProtectedDetails'
    ConflictDetails:
      type: object
      properties:
        reason:
          type:
            - string
            - 'null'
          description: Why the app would ask, for example file_in_transfer
        existing:
          oneOf:
            - type: object
              properties:
                id:
                  type: string
                name:
                  type: string
              required:
                - id
                - name
            - type: 'null'
          description: The file that holds the name
        answer_with:
          type: string
          enum:
            - on_conflict
          description: The request field that carries your answer
        choices:
          type: array
          items:
            type: string
            enum:
              - version
              - separate
              - skip
      required:
        - reason
        - existing
        - answer_with
        - choices
    ChoicesDetails:
      type: object
      properties:
        choices:
          type: array
          items:
            type: string
            enum:
              - separate
              - skip
      required:
        - choices
    IncompleteDetails:
      type: object
      properties:
        parts_received:
          type: integer
        parts_needed:
          type: integer
        missing_parts:
          type: array
          items:
            type: integer
          description: The part numbers still to send (at most 1000 are listed)
        missing_parts_truncated:
          type: boolean
          description: Present and true when more parts are missing than listed
      required:
        - parts_received
        - parts_needed
        - missing_parts
    TransferRef:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
        title:
          type:
            - string
            - 'null'
      required:
        - id
    TransferActiveDetails:
      type: object
      properties:
        transfers:
          type: array
          items:
            $ref: '#/components/schemas/TransferRef'
        needs_confirmation:
          type: boolean
          description: True when repeating the call with the confirmation would delete those transfers
        needs_token_setting:
          type: boolean
          description: True when the token's settings do not allow deleting transfers
        confirm_with:
          type: string
          description: The query parameter that confirms the delete
      required:
        - transfers
        - needs_confirmation
        - needs_token_setting
        - confirm_with
    ProtectedDetails:
      type: object
      properties:
        kind:
          type:
            - string
            - 'null'
        transfers:
          type: array
          items:
            $ref: '#/components/schemas/TransferRef'
      required:
        - kind
    BrandSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        summary:
          type: string
        access:
          type: string
          enum:
            - public
            - password
            - restricted
          description: >-
            public: anyone; password: anyone with the password; restricted: only people assigned to
            the brand
        is_draft:
          type: boolean
        download_approval:
          type: boolean
        indexable:
          type: boolean
        created_at:
          type: string
          format: date-time
        urls:
          type: object
          properties:
            page:
              type: string
            api:
              type: string
          required:
            - page
            - api
      required:
        - id
        - slug
        - name
        - summary
        - access
        - is_draft
        - download_approval
        - indexable
        - created_at
        - urls
    BrandList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BrandSummary'
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Pass as ?cursor= for the next page; null on the last page. Opaque: do not build or parse
            it.
      required:
        - data
        - next_cursor
    BrandFont:
      type: object
      properties:
        name:
          type: string
        custom:
          type: boolean
        source:
          type: string
          enum:
            - google
            - adobe
            - custom
        css:
          type: string
      required:
        - name
        - custom
        - source
    Brand:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        summary:
          type: string
        story:
          type: string
        industry:
          type: string
        size:
          type: string
        company_type:
          type: string
        year_founded:
          type: string
        website:
          type: string
        social:
          type: object
          properties:
            twitter:
              type: string
            facebook:
              type: string
            instagram:
              type: string
            linkedin:
              type: string
            youtube:
              type: string
            github:
              type: string
          required:
            - twitter
            - facebook
            - instagram
            - linkedin
            - youtube
            - github
        colors:
          type: object
          properties:
            primary:
              type:
                - string
                - 'null'
            secondary:
              type:
                - string
                - 'null'
            additional:
              type: array
              items:
                type: object
                properties:
                  name:
                    type:
                      - string
                      - 'null'
                  value:
                    type: string
                required:
                  - name
                  - value
          required:
            - primary
            - secondary
            - additional
        fonts:
          type: object
          properties:
            headline:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/BrandFont'
            body:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/BrandFont'
          required:
            - headline
            - body
        print_values:
          type: object
          additionalProperties: true
          description: CMYK and Pantone values entered for a color, keyed by the color's hex
        auto_logo_variants:
          type: boolean
          description: Whether black and white logo downloads are made automatically
        access:
          type: string
          enum:
            - public
            - password
            - restricted
          description: >-
            public: anyone; password: anyone with the password; restricted: only people assigned to
            the brand
        is_draft:
          type: boolean
        download_approval:
          type: boolean
        indexable:
          type: boolean
        tracking:
          type: object
          properties:
            ga4:
              type: string
            gtm:
              type: string
            search_console:
              type: string
            adobe_kit:
              type: string
          required:
            - ga4
            - gtm
            - search_console
            - adobe_kit
        seo:
          type: object
          properties:
            title:
              type:
                - string
                - 'null'
            description:
              type:
                - string
                - 'null'
          required:
            - title
            - description
        team:
          type: object
          properties:
            title:
              type: string
            members:
              type: array
              items:
                type: object
                properties:
                  id:
                    type:
                      - string
                      - 'null'
                  name:
                    type: string
                  title:
                    type: string
                  has_photo:
                    type: boolean
                required:
                  - id
                  - name
                  - title
                  - has_photo
          required:
            - title
            - members
        press:
          type: array
          items:
            type: object
            properties:
              id:
                type:
                  - string
                  - 'null'
              title:
                type: string
              url:
                type: string
              description:
                type: string
              image:
                type: string
              source:
                type: string
            required:
              - id
              - title
              - url
              - description
              - image
              - source
        guidelines:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              title:
                type: string
              text:
                type: string
              images:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    kind:
                      type: string
                      enum:
                        - image
                        - do
                        - dont
                    caption:
                      type: string
                  required:
                    - id
                    - kind
                    - caption
            required:
              - id
              - title
              - text
              - images
        urls:
          type: object
          properties:
            page:
              type: string
            markdown:
              type: string
            mark_usage:
              type: string
            api:
              type: string
          required:
            - page
            - markdown
            - mark_usage
            - api
        created_at:
          type: string
          format: date-time
        pictures:
          type: array
          description: >-
            Only in the answer of a create or update that named pictures by address: one entry per
            picture, ok true or false with the reason
          items:
            type: object
            properties:
              picture:
                type: string
                enum:
                  - team_photo
                  - guideline_image
              target:
                type: string
              ok:
                type: boolean
              error:
                type: string
            required:
              - picture
              - target
              - ok
      required:
        - id
        - slug
        - name
        - summary
        - story
        - industry
        - size
        - company_type
        - year_founded
        - website
        - social
        - colors
        - fonts
        - print_values
        - auto_logo_variants
        - access
        - is_draft
        - download_approval
        - indexable
        - tracking
        - seo
        - team
        - press
        - guidelines
        - urls
        - created_at
    BrandCreate:
      type: object
      additionalProperties: false
      required:
        - name
        - summary
        - industry
      description: >-
        A brand needs a name, a summary and an industry from the list. Everything else is optional
        and uses the same fields as updateBrand, so a brand can be created complete in one call
        (colors, fonts, team, press, guidelines, tracking). Text limits are the app's (name 48,
        summary 200, story 2000 characters); longer values are refused. A new brand is a private
        draft. access, is_draft and confirm_public are not accepted here; use updateBrand
        afterwards. If a part cannot be saved the brand is not created.
      properties:
        summary:
          type: string
          maxLength: 200
        story:
          type: string
          maxLength: 2000
        size:
          type: string
          enum:
            - ''
            - 1 employee
            - 2-10 employees
            - 11-50 employees
            - 51-200 employees
            - 201-500 employees
            - 501-1000 employees
            - 1001-5000 employees
            - 5001-10,000 employees
            - 10,001+ employees
        company_type:
          type: string
          enum:
            - ''
            - Educational
            - Government Agency
            - Non-Profit
            - Partnership
            - Privately Held
            - Public Company
            - Self-Employed
            - Self-Owned
        year_founded:
          type:
            - string
            - integer
          description: A four digit year, or empty to clear
        url:
          type: string
          description: A public website address, or empty to clear. Same as website
        website:
          type: string
          description: Same as url
        twitter:
          type: string
        facebook:
          type: string
        instagram:
          type: string
        linkedin:
          type: string
        youtube:
          type: string
        github:
          type: string
        social:
          type: object
          additionalProperties: false
          properties:
            twitter:
              type: string
            facebook:
              type: string
            instagram:
              type: string
            linkedin:
              type: string
            youtube:
              type: string
            github:
              type: string
        primary_color:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
        colors:
          type: object
          additionalProperties: false
          description: >-
            primary, secondary and the extra colors. additional replaces the whole extra list (up to
            30); sending only one of secondary or additional keeps the other as it is
          properties:
            primary:
              type: string
              pattern: ^#[0-9a-fA-F]{6}$
            secondary:
              type:
                - string
                - 'null'
              pattern: ^#[0-9a-fA-F]{3,8}$
            additional:
              type: array
              maxItems: 30
              items:
                type: object
                required:
                  - value
                additionalProperties: false
                properties:
                  name:
                    type:
                      - string
                      - 'null'
                    maxLength: 60
                  value:
                    type: string
                    pattern: ^#[0-9a-fA-F]{3,8}$
        print_values:
          type: object
          additionalProperties: true
          description: CMYK and Pantone values per color hex, as GET returns them (up to 40)
        auto_logo_variants:
          type: boolean
          description: Make black and white logo downloads automatically
        fonts:
          type: object
          additionalProperties: false
          description: >-
            headline and body font, each { source: google | adobe, name } or null to clear. A Google
            name must be a Google Fonts family (checked). Adobe also needs css (the family's CSS
            name) and tracking.adobe_kit. A custom font is a file uploaded in the app; the API does
            not set one.
          properties:
            headline:
              oneOf:
                - type: 'null'
                - type: object
                  required:
                    - source
                    - name
                  additionalProperties: false
                  properties:
                    source:
                      type: string
                      enum:
                        - google
                        - adobe
                    name:
                      type: string
                      maxLength: 80
                    css:
                      type: string
                      maxLength: 60
            body:
              oneOf:
                - type: 'null'
                - type: object
                  required:
                    - source
                    - name
                  additionalProperties: false
                  properties:
                    source:
                      type: string
                      enum:
                        - google
                        - adobe
                    name:
                      type: string
                      maxLength: 80
                    css:
                      type: string
                      maxLength: 60
        team:
          type: object
          additionalProperties: false
          description: >-
            The people section: a heading (up to 30 characters) and up to 24 members. A photo is
            kept for a member you send again; photo_url sets or replaces it
          properties:
            title:
              type: string
              maxLength: 30
            members:
              type: array
              maxItems: 24
              items:
                type: object
                required:
                  - name
                additionalProperties: false
                properties:
                  id:
                    type: string
                  name:
                    type: string
                    maxLength: 80
                  title:
                    type: string
                    maxLength: 80
                  photo_url:
                    type: string
                    description: A public https image address for the photo; fetched after the text is saved
        press:
          type: array
          maxItems: 24
          items:
            type: object
            required:
              - url
            additionalProperties: false
            properties:
              id:
                type: string
              url:
                type: string
                description: A public page address
              title:
                type: string
                maxLength: 200
              description:
                type: string
                maxLength: 300
              image:
                type: string
                description: A public image address shown with the article
              source:
                type: string
                maxLength: 100
          description: Articles written about the brand
        guidelines:
          type: array
          maxItems: 20
          items:
            type: object
            additionalProperties: false
            properties:
              id:
                type: string
              title:
                type: string
                maxLength: 80
              text:
                type: string
                description: 'Plain text: blank line between paragraphs, ''- '' for bullets, ''## '' for a heading'
              images:
                type: array
                maxItems: 12
                description: >-
                  Pictures to add to the section, fetched after the text is saved (an entry without
                  url is ignored, so a read can be sent back)
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    id:
                      type: string
                    url:
                      type: string
                      description: A public https image address
                    kind:
                      type: string
                      enum:
                        - image
                        - do
                        - dont
                    caption:
                      type: string
                      maxLength: 200
          description: >-
            Guideline sections (up to 20). Existing section images stay for a section you send again
            with its id; images adds more
        download_approval:
          type: boolean
        seo:
          type: object
          additionalProperties: false
          properties:
            title:
              type: string
              maxLength: 100
            description:
              type: string
              maxLength: 160
        meta_title:
          type: string
          maxLength: 100
        meta_description:
          type: string
          maxLength: 160
        team_title:
          type: string
          maxLength: 30
        tracking:
          type: object
          properties:
            ga4:
              type: string
            gtm:
              type: string
            search_console:
              type: string
            adobe_kit:
              type: string
          additionalProperties: false
          description: >-
            Google Analytics 4 id (G-...), Tag Manager id (GTM-...), Search Console token and Adobe
            Fonts project. Only the keys sent change
        name:
          type: string
          minLength: 1
          maxLength: 48
        slug:
          type: string
          maxLength: 48
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          description: Defaults to the name
        password:
          type: string
          minLength: 8
          description: >-
            Protects the brand with a password from the start (API only: the MCP never takes one). 8
            characters at least, 72 bytes at most. Stored hashed and never returned; the brand shows
            access password. It cannot be changed here afterwards; going public removes it
        industry:
          type: string
          enum:
            - Arts and Entertainment
            - Business and Consumer Services
            - Community and Society
            - Computer Electronics and Technology
            - E-commerce and Shopping
            - Finance
            - Food and Drink
            - Gambling
            - Games
            - Health
            - Heavy Industry and Engineering
            - Hobbies and Leisure
            - Home and Garden
            - Jobs and Career
            - Law and Government
            - Lifestyle
            - Luxury
            - News and Media
            - Pets and Animals
            - Reference Materials
            - Science and Education
            - Sports
            - Travel and Tourism
            - Vehicles
    BrandFileStart:
      type: object
      additionalProperties: false
      required:
        - slot
      properties:
        slot:
          type: string
          enum:
            - icon
            - main_logo
            - banner
            - social_image
            - favicon
            - logo
            - asset
            - team_photo
            - guideline_image
        size:
          type: integer
          minimum: 1
          description: The file's size in bytes; refused early when over the slot's limit
        filename:
          type: string
          maxLength: 255
          description: The file's name; refused early when its extension is not allowed for the slot
    BrandFileUpload:
      type: object
      properties:
        file_id:
          type: string
        slot:
          type: string
        upload:
          type: object
          properties:
            method:
              type: string
              enum:
                - PUT
            url:
              type: string
            expires_in:
              type: integer
          required:
            - method
            - url
            - expires_in
        max_bytes:
          type: integer
        extensions:
          type:
            - array
            - 'null'
          items:
            type: string
          description: 'null: any type'
        complete_url:
          type: string
      required:
        - file_id
        - slot
        - upload
        - max_bytes
        - extensions
        - complete_url
    BrandFileComplete:
      type: object
      additionalProperties: false
      description: >-
        Empty for icon, main_logo, banner, social_image and favicon. For logo: name, type, usage.
        For asset: collection_id or collection_name, name, type. For team_photo: member_id or
        member_name. For guideline_image: section_id, kind, caption.
      properties:
        name:
          type: string
          maxLength: 120
        type:
          type: string
          maxLength: 100
          description: >-
            For logo: primary, secondary, monochrome, reversed, icon, favicon, square or social
            media. For asset: the file type, for example image/png
        usage:
          type: string
          enum:
            - digital
            - print
            - all purpose
        collection_id:
          type: string
          format: uuid
        collection_name:
          type: string
          maxLength: 80
        member_id:
          type: string
        member_name:
          type: string
          maxLength: 80
        section_id:
          type: string
        kind:
          type: string
          enum:
            - image
            - do
            - dont
        caption:
          type: string
          maxLength: 200
    BrandFileImport:
      type: object
      additionalProperties: false
      required:
        - slot
        - url
      description: >-
        slot and url, plus for logo: name, type, usage; for asset: collection_id or collection_name,
        name, type; for team_photo: member_id or member_name; for guideline_image: section_id, kind,
        caption.
      properties:
        slot:
          type: string
          enum:
            - icon
            - main_logo
            - banner
            - social_image
            - favicon
            - logo
            - asset
            - team_photo
            - guideline_image
        url:
          type: string
          description: The https address of a public image
        name:
          type: string
          maxLength: 120
        type:
          type: string
          maxLength: 100
        usage:
          type: string
          enum:
            - digital
            - print
            - all purpose
        collection_id:
          type: string
          format: uuid
        collection_name:
          type: string
          maxLength: 80
        member_id:
          type: string
        member_name:
          type: string
          maxLength: 80
        section_id:
          type: string
        kind:
          type: string
          enum:
            - image
            - do
            - dont
        caption:
          type: string
          maxLength: 200
    BrandFileAttached:
      type: object
      properties:
        slot:
          type: string
        file_id:
          type: string
        size:
          type:
            - integer
            - 'null'
        already_attached:
          type: boolean
        logo_id:
          type: string
          format: uuid
        collection_id:
          type: string
          format: uuid
        asset_file_id:
          type: string
          format: uuid
        member_id:
          type: string
        section_id:
          type: string
        image_id:
          type: string
      required:
        - slot
        - file_id
        - size
        - already_attached
    BrandFileRemoved:
      type: object
      properties:
        removed:
          type: object
          properties:
            slot:
              type: string
            removed_id:
              type:
                - string
                - 'null'
          required:
            - slot
            - removed_id
      required:
        - removed
    DnsRecord:
      type: object
      properties:
        type:
          type:
            - string
            - 'null'
        host:
          type:
            - string
            - 'null'
        value:
          type:
            - string
            - 'null'
        purpose:
          type:
            - string
            - 'null'
        status:
          type: string
      required:
        - type
        - host
        - value
        - purpose
        - status
    BrandDomain:
      type: object
      properties:
        id:
          type: string
          format: uuid
        brand_id:
          type: string
          format: uuid
        domain:
          type: string
        status:
          type: string
          enum:
            - ownership_verification_required
            - dns_configuration_required
            - certificate_pending
            - active
          description: >-
            Where the setup stands. Add the dns_records at your DNS host; active means the domain
            serves the brand page
        status_message:
          type: string
        certificate_status:
          type:
            - string
            - 'null'
        dns_records:
          type: array
          items:
            $ref: '#/components/schemas/DnsRecord'
        last_checked_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        provider_unavailable:
          type: boolean
          description: >-
            Only on getBrandDomain: true when the hosting provider could not be reached and the
            stored values are shown
        dns_provider:
          anyOf:
            - type: 'null'
            - type: object
              additionalProperties: false
              required:
                - id
                - name
                - dashboard_url
                - nameservers
              properties:
                id:
                  type:
                    - string
                    - 'null'
                name:
                  type:
                    - string
                    - 'null'
                dashboard_url:
                  type:
                    - string
                    - 'null'
                nameservers:
                  type: array
                  items:
                    type: string
          description: >-
            Who hosts the DNS of the domain, found from its nameservers (Cloudflare, Vercel, Route
            53, GoDaddy and others). id and name are null when the host is not recognised. null when
            the nameservers could not be read
        dns_zone:
          type:
            - string
            - 'null'
          description: >-
            The DNS zone the records belong in (for brand.example.com usually example.com). null
            when it could not be found
        dns_guide:
          type: object
          description: >-
            Ready-made instructions to finish the setup by hand or by a tool that can edit DNS.
            Records are named relative to dns_zone
          properties:
            records:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                  name:
                    type: string
                  fqdn:
                    type: string
                  value:
                    type: string
                  ttl:
                    type: integer
                  proxied:
                    type: boolean
                  purpose:
                    type:
                      - string
                      - 'null'
                  status:
                    type: string
                required:
                  - type
                  - name
                  - fqdn
                  - value
                  - ttl
                  - proxied
                  - purpose
                  - status
            steps:
              type: array
              items:
                type: string
            apply_with:
              type: array
              items:
                type: object
                properties:
                  tool:
                    type: string
                  how:
                    type: string
                required:
                  - tool
                  - how
            verify:
              type: object
              properties:
                method:
                  type: string
                path:
                  type: string
                poll_every_seconds:
                  type: integer
                done_when:
                  type: string
                note:
                  type: string
              required:
                - method
                - path
                - poll_every_seconds
                - done_when
                - note
            notes:
              type: array
              items:
                type: string
      required:
        - id
        - brand_id
        - domain
        - status
        - status_message
        - certificate_status
        - dns_records
        - last_checked_at
        - created_at
    BrandDomainSet:
      type: object
      additionalProperties: false
      required:
        - domain
      properties:
        domain:
          type: string
          description: A hostname such as brand.example.com (no path, port or spaces)
    BrandDomainDeleted:
      type: object
      properties:
        deleted:
          type: boolean
        domain:
          type: string
      required:
        - deleted
        - domain
    BrandLookupRequest:
      type: object
      additionalProperties: false
      required:
        - domain
      properties:
        domain:
          type: string
          description: A public website name or address such as acme.com or https://www.acme.com
    BrandLookup:
      type: object
      properties:
        domain:
          type: string
        brand:
          $ref: '#/components/schemas/BrandCreate'
          description: >-
            Suggested fields, in the shape createBrand and updateBrand take. Only fields that were
            found are present; name is always present
        files:
          type: object
          additionalProperties: false
          properties:
            main_logo:
              type: string
            icon:
              type: string
            banner:
              type: string
          description: >-
            Public picture addresses found for the brand. Import one with the brand file upload
            (import_url)
        sources:
          type: object
          additionalProperties:
            type: string
          description: Which provider gave each value (brandfetch, context.dev, logo.dev or site)
        missing:
          type: array
          items:
            type: string
          description: Fields and files that were not found
      required:
        - domain
        - brand
        - files
        - sources
        - missing
    ArchivedBrand:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        archived_at:
          type: string
          format: date-time
        domains:
          type: array
          items:
            type: string
      required:
        - id
        - slug
        - name
        - archived_at
        - domains
    ArchivedBrandList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ArchivedBrand'
      required:
        - data
    BrandRestore:
      type: object
      additionalProperties: false
      properties:
        slug:
          type: string
          maxLength: 48
          description: Another address, when the old one is used now
    BrandPatch:
      type: object
      additionalProperties: false
      minProperties: 1
      description: >-
        Send only what changes. Every field GET /brands/{brand} returns can be sent back in the same
        shape (colors, social, seo, team, website, fonts), and the older flat names (primary_color,
        twitter, meta_title, team_title, url) still work. A list you send replaces the stored list
        (colors.additional, team.members, press, guidelines). Logos, the banner and collection files
        go through the files endpoints; team photos and guideline images can also be sent by address
        (photo_url, images) and are kept when you resend the same team member or guideline section.
        The slug, passwords and custom fonts cannot be changed here. Making a brand public needs
        confirm_public: true.
      properties:
        summary:
          type: string
          maxLength: 200
        story:
          type: string
          maxLength: 2000
        size:
          type: string
          enum:
            - ''
            - 1 employee
            - 2-10 employees
            - 11-50 employees
            - 51-200 employees
            - 201-500 employees
            - 501-1000 employees
            - 1001-5000 employees
            - 5001-10,000 employees
            - 10,001+ employees
        company_type:
          type: string
          enum:
            - ''
            - Educational
            - Government Agency
            - Non-Profit
            - Partnership
            - Privately Held
            - Public Company
            - Self-Employed
            - Self-Owned
        year_founded:
          type:
            - string
            - integer
          description: A four digit year, or empty to clear
        url:
          type: string
          description: A public website address, or empty to clear. Same as website
        website:
          type: string
          description: Same as url
        twitter:
          type: string
        facebook:
          type: string
        instagram:
          type: string
        linkedin:
          type: string
        youtube:
          type: string
        github:
          type: string
        social:
          type: object
          additionalProperties: false
          properties:
            twitter:
              type: string
            facebook:
              type: string
            instagram:
              type: string
            linkedin:
              type: string
            youtube:
              type: string
            github:
              type: string
        primary_color:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
        colors:
          type: object
          additionalProperties: false
          description: >-
            primary, secondary and the extra colors. additional replaces the whole extra list (up to
            30); sending only one of secondary or additional keeps the other as it is
          properties:
            primary:
              type: string
              pattern: ^#[0-9a-fA-F]{6}$
            secondary:
              type:
                - string
                - 'null'
              pattern: ^#[0-9a-fA-F]{3,8}$
            additional:
              type: array
              maxItems: 30
              items:
                type: object
                required:
                  - value
                additionalProperties: false
                properties:
                  name:
                    type:
                      - string
                      - 'null'
                    maxLength: 60
                  value:
                    type: string
                    pattern: ^#[0-9a-fA-F]{3,8}$
        print_values:
          type: object
          additionalProperties: true
          description: CMYK and Pantone values per color hex, as GET returns them (up to 40)
        auto_logo_variants:
          type: boolean
          description: Make black and white logo downloads automatically
        fonts:
          type: object
          additionalProperties: false
          description: >-
            headline and body font, each { source: google | adobe, name } or null to clear. A Google
            name must be a Google Fonts family (checked). Adobe also needs css (the family's CSS
            name) and tracking.adobe_kit. A custom font is a file uploaded in the app; the API does
            not set one.
          properties:
            headline:
              oneOf:
                - type: 'null'
                - type: object
                  required:
                    - source
                    - name
                  additionalProperties: false
                  properties:
                    source:
                      type: string
                      enum:
                        - google
                        - adobe
                    name:
                      type: string
                      maxLength: 80
                    css:
                      type: string
                      maxLength: 60
            body:
              oneOf:
                - type: 'null'
                - type: object
                  required:
                    - source
                    - name
                  additionalProperties: false
                  properties:
                    source:
                      type: string
                      enum:
                        - google
                        - adobe
                    name:
                      type: string
                      maxLength: 80
                    css:
                      type: string
                      maxLength: 60
        team:
          type: object
          additionalProperties: false
          description: >-
            The people section: a heading (up to 30 characters) and up to 24 members. A photo is
            kept for a member you send again; photo_url sets or replaces it
          properties:
            title:
              type: string
              maxLength: 30
            members:
              type: array
              maxItems: 24
              items:
                type: object
                required:
                  - name
                additionalProperties: false
                properties:
                  id:
                    type: string
                  name:
                    type: string
                    maxLength: 80
                  title:
                    type: string
                    maxLength: 80
                  photo_url:
                    type: string
                    description: A public https image address for the photo; fetched after the text is saved
        press:
          type: array
          maxItems: 24
          items:
            type: object
            required:
              - url
            additionalProperties: false
            properties:
              id:
                type: string
              url:
                type: string
                description: A public page address
              title:
                type: string
                maxLength: 200
              description:
                type: string
                maxLength: 300
              image:
                type: string
                description: A public image address shown with the article
              source:
                type: string
                maxLength: 100
          description: Articles written about the brand
        guidelines:
          type: array
          maxItems: 20
          items:
            type: object
            additionalProperties: false
            properties:
              id:
                type: string
              title:
                type: string
                maxLength: 80
              text:
                type: string
                description: 'Plain text: blank line between paragraphs, ''- '' for bullets, ''## '' for a heading'
              images:
                type: array
                maxItems: 12
                description: >-
                  Pictures to add to the section, fetched after the text is saved (an entry without
                  url is ignored, so a read can be sent back)
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    id:
                      type: string
                    url:
                      type: string
                      description: A public https image address
                    kind:
                      type: string
                      enum:
                        - image
                        - do
                        - dont
                    caption:
                      type: string
                      maxLength: 200
          description: >-
            Guideline sections (up to 20). Existing section images stay for a section you send again
            with its id; images adds more
        download_approval:
          type: boolean
        seo:
          type: object
          additionalProperties: false
          properties:
            title:
              type: string
              maxLength: 100
            description:
              type: string
              maxLength: 160
        meta_title:
          type: string
          maxLength: 100
        meta_description:
          type: string
          maxLength: 160
        team_title:
          type: string
          maxLength: 30
        tracking:
          type: object
          properties:
            ga4:
              type: string
            gtm:
              type: string
            search_console:
              type: string
            adobe_kit:
              type: string
          additionalProperties: false
          description: >-
            Google Analytics 4 id (G-...), Tag Manager id (GTM-...), Search Console token and Adobe
            Fonts project. Only the keys sent change
        name:
          type: string
          minLength: 1
          maxLength: 48
        industry:
          type: string
          enum:
            - Arts and Entertainment
            - Business and Consumer Services
            - Community and Society
            - Computer Electronics and Technology
            - E-commerce and Shopping
            - Finance
            - Food and Drink
            - Gambling
            - Games
            - Health
            - Heavy Industry and Engineering
            - Hobbies and Leisure
            - Home and Garden
            - Jobs and Career
            - Law and Government
            - Lifestyle
            - Luxury
            - News and Media
            - Pets and Animals
            - Reference Materials
            - Science and Education
            - Sports
            - Travel and Tourism
            - Vehicles
            - ''
        access:
          type: string
          enum:
            - public
            - restricted
          description: >-
            public also removes the password. restricted needs a contact or organization assigned
            first
        confirm_public:
          type: boolean
          description: >-
            Must be true when access changes to public on a brand that is not public yet; otherwise
            the call is refused (400 confirmation_required)
        is_draft:
          type: boolean
    BrandAssets:
      type: object
      properties:
        brand:
          type: object
          properties:
            id:
              type: string
              format: uuid
            slug:
              type: string
          required:
            - id
            - slug
        images:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                  - icon
                  - main_logo
                  - banner
              name:
                type: string
              download_url:
                type: string
            required:
              - role
              - name
              - download_url
        logos:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              type:
                type:
                  - string
                  - 'null'
              download_url:
                type: string
            required:
              - id
              - name
              - type
              - download_url
        collections:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              description:
                type: string
              files:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    name:
                      type: string
                    type:
                      type:
                        - string
                        - 'null'
                    size:
                      type:
                        - string
                        - 'null'
                    download_url:
                      type: string
                  required:
                    - id
                    - name
                    - type
                    - size
                    - download_url
            required:
              - id
              - name
              - description
              - files
        links_expire:
          type: boolean
          description: 'Always true: the download links are short-lived; list again for fresh ones'
      required:
        - brand
        - images
        - logos
        - collections
        - links_expire
    Series:
      type: array
      items:
        type: object
        properties:
          date:
            type: string
          count:
            type: integer
        required:
          - date
    BrandAnalytics:
      type: object
      properties:
        period:
          type: string
          enum:
            - 30d
            - 90d
            - all
        views:
          type: object
          properties:
            total:
              type: integer
            series:
              $ref: '#/components/schemas/Series'
          required:
            - total
            - series
        downloads:
          type: object
          properties:
            total:
              type: integer
            series:
              $ref: '#/components/schemas/Series'
          required:
            - total
            - series
        requests:
          type: object
          properties:
            total:
              type: integer
            series:
              $ref: '#/components/schemas/Series'
          required:
            - total
            - series
        downloaded_files:
          oneOf:
            - type: 'null'
            - type: object
              properties:
                top_assets:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      count:
                        type: integer
                    required:
                      - name
                      - count
                formats:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      count:
                        type: integer
                    required:
                      - name
                      - count
                unrecorded:
                  type: integer
              required:
                - top_assets
                - formats
                - unrecorded
          description: >-
            The most downloaded files and the formats taken in the period; null until the file
            columns exist. Downloads from before files were recorded are counted in `unrecorded`.
      required:
        - period
        - views
        - downloads
        - requests
        - downloaded_files
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
        description:
          type:
            - string
            - 'null'
        events:
          type: array
          items:
            type: string
          description: The event types this endpoint receives, or ["*"] for every event
        enabled:
          type: boolean
        disabled_reason:
          oneOf:
            - type: 'null'
            - type: object
              properties:
                code:
                  type: string
                message:
                  type: string
              required:
                - code
                - message
          description: >-
            Why the endpoint is off: turned_off, no_success_for_5_days, deliveries_kept_failing or
            endpoint_gone
        disabled_at:
          type:
            - string
            - 'null'
          format: date-time
        last_success_at:
          type:
            - string
            - 'null'
          format: date-time
        last_failure_at:
          type:
            - string
            - 'null'
          format: date-time
        failed_attempts_in_a_row:
          type: integer
        secret_rotation_ends_at:
          type:
            - string
            - 'null'
          format: date-time
          description: 'While a rotated secret is still signing alongside the new one: when it stops'
        created_at:
          type: string
          format: date-time
      required:
        - id
        - url
        - description
        - events
        - enabled
        - disabled_reason
        - disabled_at
        - last_success_at
        - last_failure_at
        - failed_attempts_in_a_row
        - secret_rotation_ends_at
        - created_at
    WebhookEndpointList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEndpoint'
      required:
        - data
    WebhookEndpointCreate:
      type: object
      properties:
        url:
          type: string
          description: >-
            https only, a public name (no IP number, localhost or internal name), port 443 or 1024
            and up, at most 2000 characters
        events:
          type: array
          items:
            type: string
          description: Event types to receive; omit for every event
        description:
          type:
            - string
            - 'null'
          maxLength: 200
      required:
        - url
    WebhookEndpointUpdate:
      type: object
      description: At least one field.
      properties:
        url:
          type: string
        events:
          type: array
          items:
            type: string
        description:
          type:
            - string
            - 'null'
          maxLength: 200
        enabled:
          type: boolean
          description: false stops deliveries; true starts them again and clears the failure count
    WebhookEndpointCreated:
      type: object
      properties:
        endpoint:
          $ref: '#/components/schemas/WebhookEndpoint'
        secret:
          type: string
          description: The signing secret (whsec_...). It is shown only now
      required:
        - endpoint
        - secret
    WebhookSecretRotated:
      type: object
      properties:
        secret:
          type: string
          description: The new signing secret. It is shown only now
        previous_secret_expires_at:
          type: string
          format: date-time
          description: The old secret also signs until then
      required:
        - secret
        - previous_secret_expires_at
    WebhookDelivery:
      type: object
      properties:
        id:
          type: string
          format: uuid
        event_id:
          type: string
          description: The id inside the event body; the same on every retry, so a receiver can ignore a repeat
        event_type:
          type: string
        status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
          description: 'pending: waiting for a try; failed: every try was used'
        attempts:
          type: integer
        next_attempt_at:
          type:
            - string
            - 'null'
          format: date-time
        response_status:
          type:
            - integer
            - 'null'
        error:
          type:
            - string
            - 'null'
        response_body:
          type:
            - string
            - 'null'
          description: The start of the receiver's answer
        attempt_log:
          type: array
          items:
            type: object
            properties:
              at:
                type: string
                format: date-time
              status:
                type:
                  - integer
                  - 'null'
              error:
                type:
                  - string
                  - 'null'
              ms:
                type:
                  - integer
                  - 'null'
            required:
              - at
              - status
              - error
              - ms
        created_at:
          type: string
          format: date-time
        delivered_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - event_id
        - event_type
        - status
        - attempts
        - next_attempt_at
        - response_status
        - error
        - response_body
        - attempt_log
        - created_at
        - delivered_at
    WebhookDeliveryList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookDelivery'
      required:
        - data
    WebhookDeleted:
      type: object
      properties:
        deleted:
          type: boolean
      required:
        - deleted
    WebhookEvent:
      type: object
      properties:
        id:
          type: string
          description: evt_..., stable across retries
        type:
          type: string
          description: For example webhook.test
        api_version:
          type: string
          enum:
            - v1
        created_at:
          type: string
          format: date-time
        workspace_key:
          type: string
        data:
          type: object
          additionalProperties: true
      required:
        - id
        - type
        - api_version
        - created_at
        - workspace_key
        - data
    AccessRequest:
      type: object
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - download
            - view
        name:
          type: string
        company:
          type:
            - string
            - 'null'
        email:
          type: string
        message:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - pending
            - approved
            - rejected
        created_at:
          type: string
          format: date-time
        decided_at:
          oneOf:
            - type: 'null'
            - type: string
              format: date-time
      required:
        - id
        - kind
        - name
        - company
        - email
        - message
        - status
        - created_at
        - decided_at
    RequestList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AccessRequest'
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Pass as ?cursor= for the next page; null on the last page. Opaque: do not build or parse
            it.
      required:
        - data
        - next_cursor
    Decision:
      type: object
      properties:
        action:
          type: string
          enum:
            - approve
            - reject
      required:
        - action
    DecisionResult:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - approved
            - rejected
        emailed:
          type: boolean
      required:
        - id
        - status
    Entry:
      type: object
      properties:
        id:
          type: string
          description: A file id is digits, a folder id is a uuid
        type:
          type: string
          enum:
            - file
            - folder
        name:
          type: string
        size:
          type:
            - integer
            - 'null'
          minimum: 0
          description: Bytes. null for a folder
        category:
          type:
            - string
            - 'null'
          description: >-
            The file type the app tags it with, for example image, video or document. null for a
            folder
        parent_id:
          type:
            - string
            - 'null'
          description: The id of the folder it sits in. null in the library root
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        modified_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The file's own modification time when the uploader set one, else updated_at
        sha256:
          type:
            - string
            - 'null'
          description: SHA-256 of the bytes as lowercase hex, when known. null for a folder
        sha256_source:
          type:
            - string
            - 'null'
          enum:
            - server
            - client
            - null
          description: 'server: we verified it; client: the uploader''s unverified claim'
        etag:
          type:
            - string
            - 'null'
          description: A marker that changes when the file changes. null for a folder
        protected:
          type: boolean
          description: >-
            True when a protection rule applies to the item; protection_kind says which. Some writes
            on protected items are refused
        protection_kind:
          type:
            - string
            - 'null'
          enum:
            - system
            - request
            - team
            - transfer
            - null
        visibility:
          type:
            - string
            - 'null'
          enum:
            - private
            - workspace
            - null
          description: >-
            A folder is private (its creator, whoever it was shared with, owners and admins) or
            workspace (every member sees it). null for a file
        path:
          type: string
          description: >-
            The absolute path. Present on single-item reads, on writes and in a recursive listing;
            absent from a plain folder listing
      required:
        - id
        - type
        - name
        - size
        - category
        - parent_id
        - created_at
        - updated_at
        - modified_at
        - sha256
        - sha256_source
        - etag
        - protected
        - protection_kind
        - visibility
    EntryWithPath:
      type: object
      properties:
        id:
          type: string
          description: A file id is digits, a folder id is a uuid
        type:
          type: string
          enum:
            - file
            - folder
        name:
          type: string
        size:
          type:
            - integer
            - 'null'
          minimum: 0
          description: Bytes. null for a folder
        category:
          type:
            - string
            - 'null'
          description: >-
            The file type the app tags it with, for example image, video or document. null for a
            folder
        parent_id:
          type:
            - string
            - 'null'
          description: The id of the folder it sits in. null in the library root
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        modified_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The file's own modification time when the uploader set one, else updated_at
        sha256:
          type:
            - string
            - 'null'
          description: SHA-256 of the bytes as lowercase hex, when known. null for a folder
        sha256_source:
          type:
            - string
            - 'null'
          enum:
            - server
            - client
            - null
          description: 'server: we verified it; client: the uploader''s unverified claim'
        etag:
          type:
            - string
            - 'null'
          description: A marker that changes when the file changes. null for a folder
        protected:
          type: boolean
          description: >-
            True when a protection rule applies to the item; protection_kind says which. Some writes
            on protected items are refused
        protection_kind:
          type:
            - string
            - 'null'
          enum:
            - system
            - request
            - team
            - transfer
            - null
        visibility:
          type:
            - string
            - 'null'
          enum:
            - private
            - workspace
            - null
          description: >-
            A folder is private (its creator, whoever it was shared with, owners and admins) or
            workspace (every member sees it). null for a file
        path:
          type: string
          description: The absolute path, such as /photos/2026/a.jpg
      required:
        - id
        - type
        - name
        - size
        - category
        - parent_id
        - created_at
        - updated_at
        - modified_at
        - sha256
        - sha256_source
        - etag
        - protected
        - protection_kind
        - visibility
        - path
    FileList:
      type: object
      properties:
        folder:
          type: object
          properties:
            id:
              type:
                - string
                - 'null'
              description: The folder that was listed; null for the library root
          required:
            - id
        entries:
          type: array
          items:
            $ref: '#/components/schemas/Entry'
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Pass as ?cursor= for the next page; null on the last page. Opaque: do not build or parse
            it.
      required:
        - folder
        - entries
        - next_cursor
    FileSearch:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              file_id:
                type: integer
              name:
                type: string
              folder_id:
                type:
                  - string
                  - 'null'
                format: uuid
              page:
                type:
                  - integer
                  - 'null'
              snippet:
                type: string
            required:
              - file_id
              - name
              - folder_id
              - page
              - snippet
        coverage:
          type: object
          properties:
            files:
              type: integer
            searched:
              type: integer
            notSearchable:
              type: integer
            waiting:
              type: integer
            partial:
              type: integer
              description: 'Searched files too long to index completely: only their first part is searchable'
          required:
            - files
            - searched
            - notSearchable
            - waiting
            - partial
      required:
        - results
        - coverage
    AskRequest:
      type: object
      properties:
        question:
          type: string
          minLength: 1
          maxLength: 4000
          description: >-
            What to ask about the files. Each call is a separate question: nothing from an earlier
            call is remembered.
        folder:
          type: string
          format: uuid
          description: Only answer from this folder and its subfolders
        mode:
          type: string
          enum:
            - basic
            - deep
          default: basic
          description: deep is slower and thorough; Pro plans and organizations with their own AI key only
        history:
          type: array
          maxItems: 20
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                  - user
                  - assistant
              content:
                type: string
                minLength: 1
                maxLength: 8000
            required:
              - role
              - content
          description: >-
            Earlier questions and answers of this conversation, oldest first, so a follow-up makes
            sense; each is charged as input
      required:
        - question
    AskAnswer:
      type: object
      properties:
        answer:
          type: string
          description: The answer; the files it used are cited as [1], [2]
        sources:
          type: array
          items:
            type: object
            properties:
              'n':
                type: integer
              file_id:
                type:
                  - integer
                  - 'null'
              name:
                type: string
              pages:
                type: array
                items:
                  type: integer
            required:
              - 'n'
              - file_id
              - name
              - pages
        credits_used:
          type: number
          description: AI credits this question used
        paid_by:
          type:
            - string
            - 'null'
          description: plan, extra or key
        mode:
          type: string
          enum:
            - basic
            - deep
        notes:
          type: array
          items:
            type: string
          description: >-
            Estimates made before a big read, e.g. "Looked at pages: about 160 credits" (from the
            file size); credits_used is the real total. Empty for most questions
      required:
        - answer
        - sources
        - credits_used
        - paid_by
        - mode
        - notes
    FileText:
      type: object
      properties:
        file_id:
          type: integer
        name:
          type: string
        text:
          type: string
        from_page:
          type:
            - integer
            - 'null'
        to_page:
          type:
            - integer
            - 'null'
        truncated:
          type: boolean
      required:
        - file_id
        - name
        - text
        - from_page
        - to_page
        - truncated
    FileDownload:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        size:
          type: integer
          minimum: 0
          description: Bytes
        download_url:
          type: string
          format: uri
          description: A signed URL; no token needed to fetch it
        expires_in:
          type: integer
          description: Seconds the URL keeps working (900)
        links_expire:
          type: boolean
          description: 'Always true: ask again for a fresh link'
      required:
        - id
        - name
        - size
        - download_url
        - expires_in
        - links_expire
    FolderCreate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: The folder name, at most 255 bytes
        parent_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The folder to create it in. Omit or null for the library root
        visibility:
          type: string
          enum:
            - private
            - workspace
          description: >-
            private (the default): its creator, whoever it is shared with, owners and admins.
            workspace: every member of the workspace can see it
      required:
        - name
    FilePatch:
      type: object
      minProperties: 1
      description: Send at least one key. Other keys, such as a path or a parent name, are refused.
      properties:
        name:
          type: string
          minLength: 1
          description: The new name, at most 255 bytes
        parent_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Move into this folder; null moves to the library root
        modified_at:
          type: string
          format: date-time
          description: >-
            The file's own modification time: ISO 8601 with a time zone, after 1970-01-02 and at
            most one day ahead. Files only
        visibility:
          type: string
          enum:
            - private
            - workspace
          description: >-
            Folders only: who can see it. Only the person who made the folder, an owner or an admin
            can change it
    PdfEditRequest:
      type: object
      description: At least one tool. Page numbers start at 1. camelCase names are accepted too.
      properties:
        merge_file_ids:
          type: array
          items:
            type: string
          description: Ids of other PDFs (digits) to append, in order; up to 9
        keep:
          type: string
          description: Keep only these pages, like 1-3,5,8-
        remove:
          type: string
          description: Remove these pages. Use keep or remove, not both
        order:
          type: array
          items:
            type: integer
          description: A new page order, like [3, 1, 2]
        rotate:
          type: array
          items:
            type: object
            properties:
              pages:
                type: string
              degrees:
                type: integer
                enum:
                  - 90
                  - 180
                  - 270
            required:
              - degrees
          description: Rotate pages clockwise
        crop:
          type: object
          properties:
            top:
              type: number
            right:
              type: number
            bottom:
              type: number
            left:
              type: number
            pages:
              type: string
          required: []
        blank_after:
          type: string
          description: Add a blank page after these pages
        blank_at_start:
          type: boolean
        page_numbers:
          oneOf:
            - type: boolean
            - type: object
              properties:
                position:
                  type: string
                  enum:
                    - bottom-center
                    - bottom-right
                    - bottom-left
                    - top-center
                    - top-right
                    - top-left
                start:
                  type: integer
              required: []
        watermark:
          type: string
          description: Text drawn over every page (hides nothing underneath)
        title:
          type: string
        author:
          type: string
        name:
          type: string
          description: The new file's name (the .pdf extension is added or corrected)
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The folder for the new file; null for the library root; omitted keeps the source's
            folder
    ConvertRequest:
      type: object
      required:
        - to
      properties:
        to:
          type: string
          enum:
            - text
            - images
            - split
            - word
            - excel
            - pdf
            - ocr
            - redact
            - compress
            - protect
            - unlock
        pages:
          type: string
          description: 'For text, images, word, excel, ocr and redact: only these pages, like 1-5'
        image_format:
          type: string
          enum:
            - png
            - jpg
          description: For images (default png)
        ranges:
          type: string
          description: 'For split: ''each'' (default) or groups like 1-3,4-6'
        more_file_ids:
          type: array
          items:
            type: string
          description: 'For pdf from pictures: the other pictures'' ids in order (the source is the first)'
        page_size:
          type: string
          enum:
            - fit
            - a4
            - letter
          description: For pdf from pictures (default fit)
        terms:
          type: array
          items:
            type: string
          description: >-
            For redact: the exact texts to black out (2 to 100 characters each, up to 50; case does
            not matter)
        emails:
          type: boolean
          description: 'For redact: black out every email address'
        level:
          type: string
          enum:
            - light
            - medium
            - strong
          description: For compress (default medium)
        password:
          type: string
          description: >-
            For protect (4 to 100 characters) and unlock (the PDF's current password). Used for this
            call only; never stored or logged
        name:
          type: string
          description: The new file's name (the right extension is added or corrected)
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The folder for the new file; null for the library root; omitted keeps the source's
            folder
    DocumentCreate:
      type: object
      required:
        - name
        - format
      properties:
        name:
          type: string
          description: The file's name; the extension is added or corrected
        format:
          type: string
          enum:
            - pdf
            - docx
            - pptx
            - md
            - xlsx
            - csv
        markdown:
          type: string
          description: >-
            For pdf, docx, pptx and md: the content in Markdown, up to 60,000 characters (at least
            20)
        table:
          type: object
          description: 'For xlsx and csv: up to 12 columns and 500 rows of text'
          properties:
            columns:
              type: array
              items:
                type: string
              minItems: 1
              maxItems: 12
            rows:
              type: array
              items:
                type: array
                items:
                  type: string
              minItems: 1
              maxItems: 500
          required:
            - columns
            - rows
        sources:
          type: array
          items:
            type: string
          description: File ids (digits) the document is based on, up to 10; a Sources list is added
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The folder; null or omitted for the library root
    TemplateFill:
      type: object
      required:
        - values
      properties:
        values:
          type: object
          description: >-
            Each placeholder name (exactly as written in the template) to text, or to a list of rows
            for a repeated block
          additionalProperties: true
        name:
          type: string
          description: The new file's name; default '<template> (filled).docx'
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The folder; omitted keeps the template's folder
    OfficeEdit:
      type: object
      description: >-
        Send the fields of the file's kind: .docx edits, inserts, track_changes; .pptx edits; .xlsx
        cells, append_rows. camelCase names are accepted too.
      properties:
        edits:
          type: array
          items:
            type: object
            properties:
              find:
                type: string
              replace:
                type: string
            required:
              - find
              - replace
          description: Exact text to find and its replacement (empty deletes), up to 50 for Word and PowerPoint
        inserts:
          type: array
          items:
            type: object
            description: >-
              One of: paragraphs (a list of text), table ({ columns, rows }), image ({ file_id,
              width_inches? }); after: some text of the paragraph to insert after (omitted: at the
              end)
            properties:
              after:
                type: string
              paragraphs:
                type: array
                items:
                  type: string
              table:
                type: object
              image:
                type: object
          description: Word only
        track_changes:
          type: boolean
          description: 'Word only: record the changes as tracked changes by Tarkle'
        cells:
          type: array
          items:
            type: object
            properties:
              sheet:
                type: string
              cell:
                type: string
              value:
                oneOf:
                  - type: string
                  - type: number
            required:
              - sheet
              - cell
              - value
          description: Excel only, up to 100; an empty value clears the cell
        append_rows:
          type: array
          items:
            type: object
            properties:
              sheet:
                type: string
              rows:
                type: array
                items:
                  type: array
                  items:
                    oneOf:
                      - type: string
                      - type: number
            required:
              - sheet
              - rows
          description: Excel only, up to 200 rows in all
        name:
          type: string
          description: The new file's name; default '<name> (edited).<ext>'
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The folder; omitted keeps the source's folder
    FileToolResult:
      type: object
      properties:
        file:
          $ref: '#/components/schemas/EntryWithPath'
        notes:
          type: array
          items:
            type: string
          description: What was done, in plain words
      required:
        - file
        - notes
    FileCopy:
      type: object
      description: Both keys are optional.
      properties:
        parent_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The destination folder; null for the library root; omitted keeps the original's folder
        name:
          type: string
          minLength: 1
          description: The new name, at most 255 bytes; omitted keeps the original's name
    DeleteResult:
      type: object
      properties:
        deleted:
          type: boolean
          description: Always true
        deleted_transfers:
          type: array
          items:
            type: integer
          description: >-
            The ids of the transfers deleted with the item (empty unless confirm_delete_transfers
            was true)
      required:
        - deleted
        - deleted_transfers
    Usage:
      type: object
      properties:
        storage:
          type: object
          properties:
            used_bytes:
              type: integer
              minimum: 0
            limit_bytes:
              type:
                - integer
                - 'null'
              minimum: 0
              description: The plan's limit; null when there is none
            free_bytes:
              type:
                - integer
                - 'null'
              minimum: 0
              description: limit_bytes minus used_bytes; null when there is no limit
          required:
            - used_bytes
            - limit_bytes
            - free_bytes
      required:
        - storage
    WorkspaceRef:
      type: object
      properties:
        workspace_key:
          type:
            - string
            - 'null'
          description: Send as X-Workspace-Key
        name:
          type:
            - string
            - 'null'
        url:
          type:
            - string
            - 'null'
        relationship:
          type: string
          enum:
            - owner
            - member
            - linked
      required:
        - workspace_key
        - name
        - url
        - relationship
    WorkspaceList:
      type: object
      properties:
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceRef'
      required:
        - workspaces
    UploadStart:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: The file name, at most 255 bytes
        size:
          type: integer
          minimum: 0
          description: The file's size in bytes. 0 creates an empty file at once
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The folder to upload into. Omit or null for the library root
        content_type:
          type: string
          maxLength: 100
          description: The media type, without control characters. Default application/octet-stream
        sha256:
          type: string
          pattern: ^[0-9a-fA-F]{64}$
          description: The SHA-256 of the file's bytes as 64 hexadecimal characters
        on_conflict:
          type: string
          enum:
            - version
            - separate
            - skip
          description: >-
            Your answer when the app's duplicate rule would ask: version, separate or skip. See
            startUpload
        modified_at:
          type: string
          format: date-time
          description: >-
            The file's own modification time: ISO 8601 with a time zone, after 1970-01-02 and at
            most one day ahead
      required:
        - name
        - size
    UploadPart:
      type: object
      properties:
        partNumber:
          type: integer
          minimum: 1
        url:
          type: string
          format: uri
          description: 'A signed URL: PUT that part''s bytes to it'
      required:
        - partNumber
        - url
    UploadStarted:
      type: object
      properties:
        action:
          type: string
          enum:
            - upload
        will_be_renamed:
          type: boolean
          description: True when the name was taken and the file will get a numbered name
        folder_id:
          type:
            - string
            - 'null'
        id:
          type: string
          format: uuid
        status:
          type: string
          description: pending, uploading, completed, failed, aborted or expired
        name:
          type: string
        size:
          type: integer
          minimum: 0
        mode:
          type: string
          enum:
            - single
            - multipart
          description: 'single: one signed URL; multipart: signed part URLs of part_size bytes each'
        part_size:
          type: integer
          minimum: 1
          description: Bytes per part (the last part can be smaller)
        part_count:
          type: integer
          minimum: 1
        expires_at:
          type: string
          format: date-time
        content_type:
          type: string
        uploads:
          type: array
          items:
            $ref: '#/components/schemas/UploadPart'
          description: 'Signed URLs: one for a single upload, the first batch of parts for a multipart upload'
      required:
        - action
        - will_be_renamed
        - folder_id
        - id
        - status
        - name
        - size
        - mode
        - part_size
        - part_count
        - expires_at
        - content_type
        - uploads
    UploadStartedVersion:
      type: object
      properties:
        action:
          type: string
          enum:
            - upload
        kind:
          type: string
          enum:
            - version
          description: This upload adds a new version to an existing file
        will_be_renamed:
          type: boolean
          description: Always false for a version
        id:
          type: string
          format: uuid
        status:
          type: string
          description: pending
        name:
          type: string
        size:
          type: integer
          minimum: 0
        file_id:
          type: string
          description: The existing file this version belongs to
        folder_id:
          type:
            - string
            - 'null'
        retention_days:
          type:
            - integer
            - 'null'
          description: How long older versions are kept; null when there is no limit
        mode:
          type: string
          enum:
            - single
            - multipart
          description: 'single: one signed URL; multipart: signed part URLs of part_size bytes each'
        part_size:
          type: integer
          minimum: 1
        part_count:
          type: integer
          minimum: 1
        multipart_id:
          type: string
          description: 'Multipart uploads only: send it back where an endpoint asks for multipart_id'
        uploads:
          type: array
          items:
            $ref: '#/components/schemas/UploadPart'
          description: 'Signed URLs: one for a single upload, the first batch of parts for a multipart upload'
      required:
        - action
        - kind
        - will_be_renamed
        - id
        - status
        - name
        - size
        - file_id
        - folder_id
        - retention_days
        - mode
        - part_size
        - part_count
        - uploads
    FileCreated:
      type: object
      properties:
        action:
          type: string
          enum:
            - created
        kind:
          type: string
          enum:
            - empty
        file:
          oneOf:
            - $ref: '#/components/schemas/EntryWithPath'
            - type: 'null'
          description: The empty file that was created
      required:
        - action
        - kind
        - file
    UploadSkipped:
      type: object
      properties:
        action:
          type: string
          enum:
            - skip
        existing:
          oneOf:
            - type: object
              properties:
                id:
                  type: string
                name:
                  type: string
              required:
                - id
                - name
            - type: 'null'
          description: The identical file that is already there
      required:
        - action
        - existing
    UploadStatus:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          description: pending, uploading, completed, failed, aborted or expired
        name:
          type: string
        size:
          type: integer
          minimum: 0
        mode:
          type: string
          enum:
            - single
            - multipart
          description: 'single: one signed URL; multipart: signed part URLs of part_size bytes each'
        part_size:
          type: integer
          minimum: 1
        part_count:
          type: integer
          minimum: 1
        expires_at:
          type: string
          format: date-time
        parts_received:
          type: integer
          minimum: 0
          description: 'Multipart uploads: how many parts have arrived'
        file:
          oneOf:
            - $ref: '#/components/schemas/EntryWithPath'
            - type: 'null'
          description: The finished file, once the upload is completed
      required:
        - id
        - status
        - name
        - size
        - mode
        - part_size
        - part_count
        - expires_at
    UploadStatusVersion:
      type: object
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - version
        status:
          type: string
          enum:
            - completed
            - pending
            - expired
        size:
          type: integer
          minimum: 0
        file_id:
          type: string
        mode:
          type: string
          enum:
            - single
            - multipart
          description: 'single: one signed URL; multipart: signed part URLs of part_size bytes each'
        part_size:
          type: integer
          minimum: 1
        part_count:
          type: integer
          minimum: 1
        parts_received:
          type: integer
          minimum: 0
          description: 'Multipart uploads: how many parts have arrived'
      required:
        - id
        - kind
        - status
        - size
        - file_id
        - mode
        - part_size
        - part_count
    UploadAborted:
      type: object
      properties:
        aborted:
          type: boolean
          description: Always true
      required:
        - aborted
    UploadPartsRequest:
      type: object
      description: All keys are optional.
      properties:
        from_part:
          type: integer
          minimum: 1
          default: 1
          description: The first part number to sign; at most part_count
        count:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
          description: How many parts to sign
        multipart_id:
          type: string
          maxLength: 1023
          description: 'For a multipart version upload: the multipart_id that startUpload returned'
    UploadParts:
      type: object
      properties:
        uploads:
          type: array
          items:
            $ref: '#/components/schemas/UploadPart'
      required:
        - uploads
    UploadCompleteRequest:
      type: object
      description: All keys are optional; an empty body is fine.
      properties:
        multipart_id:
          type: string
          maxLength: 1023
          description: 'For a multipart version upload: the multipart_id that startUpload returned'
        sha256:
          type: string
          pattern: ^[0-9a-fA-F]{64}$
          description: The SHA-256 of the file's bytes as 64 hexadecimal characters
        modified_at:
          type: string
          format: date-time
          description: >-
            The file's own modification time: ISO 8601 with a time zone, after 1970-01-02 and at
            most one day ahead
    UploadCompleted:
      type: object
      properties:
        id:
          type: string
          description: A file id is digits, a folder id is a uuid
        type:
          type: string
          enum:
            - file
            - folder
        name:
          type: string
        size:
          type:
            - integer
            - 'null'
          minimum: 0
          description: Bytes. null for a folder
        category:
          type:
            - string
            - 'null'
          description: >-
            The file type the app tags it with, for example image, video or document. null for a
            folder
        parent_id:
          type:
            - string
            - 'null'
          description: The id of the folder it sits in. null in the library root
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        modified_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The file's own modification time when the uploader set one, else updated_at
        sha256:
          type:
            - string
            - 'null'
          description: SHA-256 of the bytes as lowercase hex, when known. null for a folder
        sha256_source:
          type:
            - string
            - 'null'
          enum:
            - server
            - client
            - null
          description: 'server: we verified it; client: the uploader''s unverified claim'
        etag:
          type:
            - string
            - 'null'
          description: A marker that changes when the file changes. null for a folder
        protected:
          type: boolean
          description: >-
            True when a protection rule applies to the item; protection_kind says which. Some writes
            on protected items are refused
        protection_kind:
          type:
            - string
            - 'null'
          enum:
            - system
            - request
            - team
            - transfer
            - null
        visibility:
          type:
            - string
            - 'null'
          enum:
            - private
            - workspace
            - null
          description: >-
            A folder is private (its creator, whoever it was shared with, owners and admins) or
            workspace (every member sees it). null for a file
        path:
          type: string
          description: The absolute path, such as /photos/2026/a.jpg
        version_created:
          type: boolean
          description: >-
            Version uploads only: false when the bytes were identical to the current version, so
            nothing was added
      required:
        - id
        - type
        - name
        - size
        - category
        - parent_id
        - created_at
        - updated_at
        - modified_at
        - sha256
        - sha256_source
        - etag
        - protected
        - protection_kind
        - visibility
        - path
    TransferItem:
      type: object
      properties:
        id:
          type: string
          description: >-
            A file id (digits) or a folder id (uuid), already in the library (upload it first with
            POST /uploads)
        type:
          type: string
          enum:
            - file
            - folder
      required:
        - id
        - type
    TransferCreate:
      type: object
      properties:
        type:
          type: string
          enum:
            - standard
            - video
            - audio
            - canvas
          default: standard
          description: >-
            standard: a plain file/folder link (the rest of this schema). video/audio: a single
            already-uploaded file of that type, wrapped in a media player. canvas: one or more
            PDF/image files as a feedback board -- see TransferCreateRich for those three
        items:
          type: array
          items:
            $ref: '#/components/schemas/TransferItem'
          minItems: 1
          description: 'At least one existing file or folder from the library (type: standard only)'
        access:
          type: string
          enum:
            - public
            - password
          description: 'public: anyone with the link; password: also needs the password'
        password:
          type: string
          minLength: 1
          description: Required when access is "password"
        title:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the link stops working. Must be in the future. Omit or null for a link that never
            expires
        burn_after_read:
          type: boolean
          description: The link stops working after its first download
        view_only:
          type: boolean
        download_mode:
          type: string
          enum:
            - standard
            - email_required
            - direct
          default: standard
        feedback_deadline_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            type: canvas only. When board comments close. Must be in the future. Omit or null to
            never close
      required:
        - items
        - access
    Transfer:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
          description: The public share link
        type:
          type: string
          enum:
            - standard
            - video
            - audio
            - canvas
          description: >-
            video/audio/canvas transfers only answer id, url and type -- see TransferCreate's type
            field
        slug:
          type: string
        title:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        access:
          type: string
          enum:
            - public
            - password
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        burn_after_read:
          type: boolean
        view_only:
          type: boolean
        download_mode:
          type: string
          enum:
            - standard
            - email_required
            - direct
        created_at:
          type: string
          format: date-time
      required:
        - id
        - url
    TransferDeleted:
      type: object
      properties:
        deleted:
          type: boolean
        id:
          type: string
      required:
        - deleted
        - id
    GalleryCreate:
      type: object
      properties:
        folder_id:
          type: string
          format: uuid
          description: A folder whose JPG, PNG and WebP files (directly in it, up to 500) become the gallery
        title:
          type: string
          minLength: 1
          maxLength: 120
        price:
          type: string
          pattern: ^\d{1,5}(\.\d{1,2})?$
          description: 0.01 to 99999.99 in the currency's main unit. Omit for a free gallery
        currency:
          type: string
          enum:
            - USD
            - EUR
            - GBP
            - CAD
            - AUD
            - CHF
            - SEK
            - NOK
            - DKK
            - PLN
            - CZK
            - NZD
            - SGD
            - HKD
            - MXN
          default: USD
          description: The buyer always pays in this currency
        preview_mode:
          type: string
          enum:
            - all
            - first
          default: all
          description: >-
            Paid only. all: every photo as a watermarked preview; first: only the first
            preview_count, the rest blurred
        preview_count:
          type: integer
          minimum: 0
          maximum: 6
          default: 3
        watermark:
          type: boolean
          description: Free galleries only (a paid gallery is always watermarked until bought)
        client_name:
          type: string
          maxLength: 120
          description: Shown on the gallery as "For <name>"
        client_email:
          type: string
          format: email
          description: Kept for your own use; Tarkle does not email it
      required:
        - folder_id
        - title
    GalleryPurchase:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - completed
            - refunded
          description: Only completed means the buyer paid
        amount:
          type: string
        currency:
          type: string
        buyer_name:
          type:
            - string
            - 'null'
        buyer_email:
          type:
            - string
            - 'null'
        paid_at:
          type: string
          format: date-time
        access_until:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - status
        - amount
        - currency
        - buyer_name
        - buyer_email
        - paid_at
        - access_until
    Gallery:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        title:
          type:
            - string
            - 'null'
        paid:
          type: boolean
        price:
          type:
            - string
            - 'null'
          description: '"600.00", or null for a free gallery'
        currency:
          type:
            - string
            - 'null'
        watermark:
          type: boolean
        preview_mode:
          type:
            - string
            - 'null'
          enum:
            - all
            - first
            - null
        preview_count:
          type:
            - integer
            - 'null'
        photo_count:
          type: integer
        gallery_url:
          type: string
          format: uri
          description: '/g/...: the gallery, with a Buy button when paid'
        pay_url:
          type:
            - string
            - 'null'
          format: uri
          description: '/pay/...: the checkout of a paid gallery, to send to the buyer; null when free'
        disabled:
          type: boolean
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        purchases:
          type: array
          items:
            $ref: '#/components/schemas/GalleryPurchase'
      required:
        - id
        - slug
        - title
        - paid
        - price
        - currency
        - watermark
        - preview_mode
        - preview_count
        - photo_count
        - gallery_url
        - pay_url
        - disabled
        - created_at
    ContactCreate:
      type: object
      properties:
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        organization_name:
          type: string
        business:
          type: boolean
      required:
        - email
    ContactOrganization:
      type: object
      properties:
        organizationId:
          type: string
        name:
          type: string
      required:
        - organizationId
        - name
    Contact:
      type: object
      properties:
        contactId:
          type: string
        name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        status:
          type:
            - string
            - 'null'
        portalAccess:
          type: boolean
        portalInvitedAt:
          type:
            - string
            - 'null'
          format: date-time
        portalSignedIn:
          type: boolean
        organizations:
          type: array
          items:
            $ref: '#/components/schemas/ContactOrganization'
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - contactId
        - name
        - email
        - status
        - portalAccess
        - portalInvitedAt
        - portalSignedIn
        - organizations
        - createdAt
    ContactList:
      type: object
      properties:
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
      required:
        - contacts
    ContactPortalAccessSet:
      type: object
      properties:
        enabled:
          type: boolean
      required:
        - enabled
    ContactPortalAccess:
      type: object
      properties:
        contactId:
          type: string
        portalAccess:
          type: boolean
        inviteEmailSent:
          type: boolean
      required:
        - contactId
        - portalAccess
        - inviteEmailSent
    ContactPortalInvite:
      type: object
      properties:
        contactId:
          type: string
        inviteEmailSent:
          type: boolean
      required:
        - contactId
        - inviteEmailSent
    ContactStorageLimitSet:
      type: object
      properties:
        limit_gb:
          type: number
          minimum: 1
          maximum: 10000
          description: How much the contact may upload from their portal, in GB
      required:
        - limit_gb
    ContactStorageLimitChanged:
      type: object
      properties:
        contactId:
          type: string
        limitBytes:
          type: integer
      required:
        - contactId
        - limitBytes
    ContactStorageLimit:
      type: object
      properties:
        contactId:
          type: string
        limitBytes:
          type: integer
        usedBytes:
          type: integer
          description: What the contact has uploaded from their portal so far
      required:
        - contactId
        - limitBytes
        - usedBytes
    TransferUpdate:
      type: object
      properties:
        view_only:
          type: boolean
          description: >-
            false: the people the transfer was delivered to can download its files. true: they can
            only view them
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: A future date at most three years ahead, or null to remove the expiry
        password:
          type:
            - string
            - 'null'
          minLength: 4
          maxLength: 100
          description: 4 to 100 characters, or null to remove the password. Never returned
      required: []
    TransferContactsAdd:
      type: object
      properties:
        contact_ids:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          maxItems: 50
          description: Contact ids from createContact's or listContacts' answer
      required:
        - contact_ids
    TransferContacts:
      type: object
      properties:
        id:
          type: string
        contact_ids:
          type: array
          items:
            type: string
          description: Every contact the transfer is delivered to
        added:
          type: array
          items:
            type: string
          description: The ids this call added (empty when they were all there already)
        view_only:
          type: boolean
      required:
        - id
        - contact_ids
        - added
        - view_only
    FileRequestCreate:
      type: object
      properties:
        title:
          type: string
          maxLength: 200
        description:
          type: string
          maxLength: 2000
        destination_folder:
          type:
            - string
            - 'null'
        is_public:
          type: boolean
          default: true
        email_notifications:
          type: boolean
          default: false
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Must be in the future. Omit or null for a request that never expires
      required:
        - title
    FileRequest:
      type: object
      properties:
        id:
          type: string
        shortId:
          type:
            - string
            - 'null'
        url:
          type: string
          format: uri
          description: The public upload link
        title:
          type: string
        description:
          type:
            - string
            - 'null'
        destinationFolder:
          type:
            - string
            - 'null'
        isPublic:
          type: boolean
        completed:
          type: boolean
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - shortId
        - url
        - title
        - description
        - destinationFolder
        - isPublic
        - completed
        - expiresAt
        - createdAt
    FileRequestList:
      type: object
      properties:
        fileRequests:
          type: array
          items:
            $ref: '#/components/schemas/FileRequest'
      required:
        - fileRequests
    TeamCreate:
      type: object
      properties:
        name:
          type: string
          maxLength: 120
        description:
          type: string
          maxLength: 120
        access:
          type: string
          enum:
            - everyone
            - members
          default: everyone
          description: >-
            everyone: every workspace member sees it. members: only members added later, through the
            app
        budget_gb:
          type: number
          minimum: 1
          maximum: 1000000
          description: A fixed storage budget in GB. Omit or null for no limit
      required:
        - name
    Team:
      type: object
      properties:
        id:
          type: string
        masterFolderId:
          type:
            - string
            - 'null'
        name:
          type: string
        access:
          type: string
          enum:
            - everyone
            - members
      required:
        - id
        - masterFolderId
        - name
        - access
    TeamListItem:
      type: object
      properties:
        id:
          type: string
        masterFolderId:
          type:
            - string
            - 'null'
        name:
          type: string
        description:
          type: string
        access:
          type: string
          enum:
            - everyone
            - members
        created_at:
          type: string
          format: date-time
      required:
        - id
        - masterFolderId
        - name
        - description
        - access
        - created_at
    TeamList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TeamListItem'
      required:
        - data
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Makes a write safe to repeat. Send a random value (a UUID is fine) of up to 255 visible
        characters. A repeat of the same request gets the first answer again, with the header
        `Idempotent-Replayed: true`, and does nothing twice. The same key for a different request is
        422 `idempotency_key_reused`; the same request while the first one is still running is 409
        `idempotency_in_progress`. A 5xx or 429 is not remembered, so retrying it runs the request
        again. Keys last 24 hours and belong to the account that created the token.
      schema:
        type: string
        minLength: 1
        maxLength: 255
  headers:
    RateLimitLimit:
      description: >-
        Requests allowed per minute for this API key (the plan's number: Free 50, Pro 250, Agency
        500
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left in the current minute
      schema:
        type: integer
    RateLimitReset:
      description: When the current window ends, in Unix seconds
      schema:
        type: integer
    IetfRateLimitLimit:
      description: The same limit in the IETF RateLimit header form (draft-ietf-httpapi-ratelimit-headers)
      schema:
        type: integer
    IetfRateLimitRemaining:
      description: Requests left in the current minute
      schema:
        type: integer
    IetfRateLimitReset:
      description: Seconds until the current window ends (X-RateLimit-Reset is the same moment as Unix seconds)
      schema:
        type: integer
    IetfRateLimitPolicy:
      description: >-
        The policies, for example 250;w=60, 25000;w=86400: 250 requests per 60-second window and
        25,000 per day for the organization
      schema:
        type: string
    Deprecation:
      description: >-
        Sent ONLY on a deprecated version or endpoint (none today): RFC 9745 structured date,
        "@<unix seconds>", when it was deprecated
      schema:
        type: string
    Sunset:
      description: >-
        Sent ONLY on a deprecated version or endpoint (none today): RFC 8594 HTTP-date after which
        it may stop working
      schema:
        type: string
    DeprecationLink:
      description: >-
        Sent ONLY with Deprecation: links with rel=deprecation (the policy), rel=sunset and
        rel=successor-version
      schema:
        type: string
    QuotaLimit:
      description: >-
        The organization's daily API quota (requests a day, shared by all its API keys and
        workspaces; resets at midnight UTC)
      schema:
        type: integer
    QuotaRemaining:
      description: Daily quota units left today (a search costs 5, everything else 1)
      schema:
        type: integer
    QuotaReset:
      description: When the daily quota resets (the next midnight UTC), in Unix seconds
      schema:
        type: integer
    QuotaWarning:
      description: 'Sent from 80% of the daily quota until it resets: the value is 80%'
      schema:
        type: string
    RateLimitHeavyLimit:
      description: >-
        Sent on search and AI requests: how many of them this key may make a minute (they also count
        in X-RateLimit-Limit and the daily quota)
      schema:
        type: integer
    RateLimitHeavyRemaining:
      description: 'Sent on search and AI requests: how many are left this minute'
      schema:
        type: integer
    RetryAfter:
      description: >-
        Seconds to wait before trying again: the end of the minute for rate_limited, midnight UTC
        for quota_exceeded
      schema:
        type: integer
    ApiVersion:
      description: The API version that answered
      schema:
        type: string
    WwwAuthenticate:
      description: Bearer with a resource_metadata URL (RFC 9728), on every 401
      schema:
        type: string
  responses:
    BadRequest:
      description: >-
        The request is invalid: a parameter, the body or the workspace key is wrong
        (invalid_request, invalid_name, workspace_required, confirmation_required and others). code
        says which
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: >-
        The token is missing, invalid or revoked (unauthorized), or it is an older workspace-bound
        token (legacy_token). Create a token in Settings > API. The rate-limit headers describe the
        caller's IP bucket here, since no token was identified
      headers:
        WWW-Authenticate:
          $ref: '#/components/headers/WwwAuthenticate'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: >-
        The token lacks the scope this operation needs (see x-required-scope) or has no scopes
        (token_without_scopes), has no access to the workspace (no_access), its creator may not do
        this (forbidden), or the item is protected (protected)
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: The brand, request, file, folder or upload does not exist in this workspace (not_found)
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Conflict:
      description: >-
        The request conflicts with the current state, for example a taken name (name_taken), a
        request that is already decided, an item a transfer holds (transfer_active), or missing
        upload parts (incomplete); or, on a write, a request with the same Idempotency-Key is still
        running (idempotency_in_progress). code says which
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Gone:
      description: 'Gone for good: the upload expired or failed (expired, failed)'
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    PayloadTooLarge:
      description: >-
        Over the plan's storage or file-size limit, or too large to list (storage_full,
        file_too_large, storage_limit_exceeded, too_large)
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unprocessable:
      description: >-
        The bytes do not match what was announced (integrity_mismatch, size_mismatch), or the
        Idempotency-Key was already used for a different request (idempotency_key_reused)
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    RateLimited:
      description: >-
        Too many requests (rate_limited): the key's per-minute limit, or its search and AI limit,
        was hit; wait Retry-After seconds. The organization's daily quota is used up
        (quota_exceeded): Retry-After is the seconds until midnight UTC, and a refused request costs
        no quota. Too many unfinished uploads is too_many_uploads
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ServerError:
      description: Something went wrong on our side (server_error). Try again later
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    BadGateway:
      description: Cloud storage did not answer (storage_unavailable). Try again
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unavailable:
      description: >-
        Temporarily unavailable: the files API is switched off, the plan or storage could not be
        read, or an Idempotency-Key could not be recorded so the write was not run (unavailable,
        entitlement_unresolved). Try again later
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem:
      description: >-
        Any other error. Every error of this API is a problem details object (RFC 9457,
        application/problem+json) with a stable machine-readable code and a human detail; branch on
        code and treat an unknown one by its HTTP status
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: tk_ token
      x-scopes:
        brands:read: Read brands, their assets, brand.md and analytics
        brands:write: Update a brand's text, links, access and settings
        brands:create: Create brands, delete them to the bin and restore them from it
        brands:domains: Connect, check and remove a brand's custom domain
        brands:files: Upload a brand's icon, logos, banner, social image, favicon and collection files
        brands:requests: List download and view requests and approve or reject them
        webhooks:manage: Add, change and remove webhook endpoints, send test events and read the delivery log
        files:read: List and download files and folders
        files:write: >-
          Create folders, rename and delete files and folders (and restore them from the bin);
          uploads are separate endpoints
        ai:ask: >-
          Ask a question about the library's files and get an answer with sources; it spends AI
          credits like a question in Ask about files (read-only)
        transfers:create: >-
          Create a shareable transfer link from files or folders already in the library, deliver it
          to contacts' client portals, change it (view only, expiry, password) and delete it
        transfers:read: Read a transfer's status
        contacts:create: Add a contact to the workspace
        contacts:read: List and search the workspace's contacts, and read their portal upload use
        contacts:portal: >-
          Turn a contact's client portal access on or off, resend their sign-in email and set their
          portal upload limit
        file_requests:create: Create a public upload link (a file request)
        file_requests:read: List the workspace's file requests
        teams:create: Create a team folder (Pro only, owner or admin)
      description: >-
        Scopes: brands:read (Read brands, their assets, brand.md and analytics); brands:write
        (Update a brand's text, links, access and settings); brands:create (Create brands, delete
        them to the bin and restore them from it); brands:domains (Connect, check and remove a
        brand's custom domain); brands:files (Upload a brand's icon, logos, banner, social image,
        favicon and collection files); brands:requests (List download and view requests and approve
        or reject them); webhooks:manage (Add, change and remove webhook endpoints, send test events
        and read the delivery log); files:read (List and download files and folders); files:write
        (Create folders, rename and delete files and folders (and restore them from the bin);
        uploads are separate endpoints); ai:ask (Ask a question about the library's files and get an
        answer with sources; it spends AI credits like a question in Ask about files (read-only));
        transfers:create (Create a shareable transfer link from files or folders already in the
        library, deliver it to contacts' client portals, change it (view only, expiry, password) and
        delete it); transfers:read (Read a transfer's status); contacts:create (Add a contact to the
        workspace); contacts:read (List and search the workspace's contacts, and read their portal
        upload use); contacts:portal (Turn a contact's client portal access on or off, resend their
        sign-in email and set their portal upload limit); file_requests:create (Create a public
        upload link (a file request)); file_requests:read (List the workspace's file requests);
        teams:create (Create a team folder (Pro only, owner or admin)). Create an API key in
        Settings > API.
security:
  - bearer: []
x-api-lifecycle:
  version: v1
  status: stable
  deprecation_scheduled: false
  minimum_notice_months: 6
  signalled_by:
    - Deprecation response header (RFC 9745)
    - Sunset response header (RFC 8594)
    - Link header with rel=deprecation and rel=sunset
  policy: >-
    v1 only grows (endpoints, optional fields, error codes). A breaking change ships as a new
    version in the path. The old version keeps working for at least 6 months after its Deprecation
    header first appears. No version is deprecated today, so no response carries these headers.
x-error-codes:
  invalid_request:
    status: 400
    title: Invalid request
    meaning: A field is missing, has the wrong type or is out of range.
  invalid_workspace:
    status: 400
    title: Invalid workspace key
    meaning: >-
      The workspace value is malformed. A key is eight lowercase letters and digits (GET /workspaces
      lists them).
  workspace_required:
    status: 400
    title: Workspace key required
    meaning: >-
      No workspace key was sent. Send X-Workspace-Key (or workspace_key) on every call that works
      inside a workspace.
  workspace_key_required:
    status: 400
    title: Workspace id not accepted
    meaning: A workspace id was sent where the eight-character workspace key is required.
  conflicting_workspace:
    status: 400
    title: Conflicting workspace
    meaning: >-
      The workspace is named twice with different values, for example in the header and in the
      query.
  not_supported:
    status: 400
    title: Not supported
    meaning: The operation does not apply to this item, for example a modification time on a folder.
  invalid_name:
    status: 400
    title: Invalid name
    meaning: The name is empty, is . or .., contains / or control characters, or is not valid Unicode.
  name_too_long:
    status: 400
    title: Name too long
    meaning: The name is longer than 255 bytes in UTF-8.
  invalid_destination:
    status: 400
    title: Invalid destination
    meaning: A folder cannot be moved into itself or one of its own subfolders.
  version_too_large:
    status: 400
    title: Version too large
    meaning: The file is too large to save as a new version.
  confirmation_required:
    status: 400
    title: Confirmation required
    meaning: >-
      A destructive or publishing step needs its confirmation: confirm_public: true to make a brand
      public, confirm_delete: true to archive (delete) a brand.
  direct_download_blocked_file_types:
    status: 400
    title: File type blocked for direct download
    meaning: >-
      One or more selected files cannot be sent with download_mode: "direct" for security reasons.
      details.blockedFiles names which, and why.
  unauthorized:
    status: 401
    title: Unauthorized
    meaning: The token is missing, malformed, invalid or revoked.
  legacy_token:
    status: 401
    title: Retired token
    meaning: >-
      The token is an older workspace token and no longer works. Create a new token in Settings >
      API.
  forbidden:
    status: 403
    title: Forbidden
    meaning: >-
      The token lacks the scope this operation needs, or its creator's role in the workspace is not
      enough.
  token_without_scopes:
    status: 403
    title: Token has no scopes
    meaning: The token was created before scopes existed. Create a new token and choose its scopes.
  no_access:
    status: 403
    title: No access to this workspace
    meaning: >-
      The workspace key is unknown, or the person who created the token cannot access that
      workspace. Both answer the same, so keys cannot be probed.
  workspace_suspended:
    status: 403
    title: Workspace suspended
    meaning: >-
      The workspace is suspended, so its API is closed as well. Contact support or the workspace
      owner.
  protected:
    status: 403
    title: Protected item
    meaning: >-
      The item is protected (system, request, team or transfer folders) and cannot be changed
      through the API. details.kind says why.
  domain_taken:
    status: 409
    title: Domain not available
    meaning: >-
      The domain is already used by another brand or another part of Tarkle, or it is attached
      elsewhere. details.reason names which.
  domain_rejected:
    status: 422
    title: Domain rejected
    meaning: The hosting provider refused the domain.
  domain_provider_error:
    status: 502
    title: Domain provider error
    meaning: The hosting provider could not remove the domain. The brand keeps it; retry.
  file_not_uploaded:
    status: 409
    title: File not uploaded
    meaning: Nothing was found at the upload address. PUT the file to the url, then complete the upload.
  invalid_file:
    status: 422
    title: File refused
    meaning: >-
      The uploaded file is too large, the wrong type or not what its name says. The message names
      the reason and the stored file is removed.
  not_found:
    status: 404
    title: Not found
    meaning: The item, upload or brand does not exist in this workspace.
  private_item:
    status: 403
    title: Private item
    meaning: >-
      The item exists but is private, and the person this token acts as cannot open it. Only an
      admin of a workspace with admin privacy sees this answer; ask the owner or the person who made
      it to share it.
  conflict:
    status: 409
    title: Conflict
    meaning: >-
      The request clashes with the current state, for example a file with the same name exists.
      details lists the choices.
  name_taken:
    status: 409
    title: Name already taken
    meaning: A sibling with this name already exists in the folder.
  ambiguous_path:
    status: 409
    title: Ambiguous path
    meaning: Two folders on the path share a name, so the path points at more than one item. Use ids.
  not_readable:
    status: 422
    title: Nothing to read
    meaning: >-
      The file has no text to read: a scan, picture, audio, video or archive. Search and text
      reading cover files with real text only.
  transfer_active:
    status: 409
    title: Active transfer
    meaning: >-
      The item is part of an active transfer. details.confirm_with names the field that confirms
      deleting those transfers.
  incomplete:
    status: 409
    title: Upload incomplete
    meaning: Not every part has arrived. details.missing_parts lists the parts still to send.
  empty_version_not_supported:
    status: 409
    title: Empty version not supported
    meaning: An empty file cannot be saved as a new version. details.choices lists what to send instead.
  size_unreadable:
    status: 409
    title: Size unreadable
    meaning: The source file's size could not be read.
  parent_unavailable:
    status: 409
    title: Parent folder unavailable
    meaning: The folder the item was in is in the bin or gone. Restore that folder first.
  not_multipart:
    status: 409
    title: Not a multipart upload
    meaning: The upload is a single PUT and has no parts to sign.
  not_deleted:
    status: 409
    title: Not in the bin
    meaning: Only an item in the bin can be restored.
  not_an_api_upload:
    status: 409
    title: Not an API upload
    meaning: The upload was not started through the API.
  folder_unresolved:
    status: 409
    title: Folder unresolved
    meaning: The folder of the file could not be located.
  finalizing:
    status: 409
    title: Upload is finalizing
    meaning: The upload is already being completed. Retry shortly.
  expired:
    status: 410
    title: Expired
    meaning: The upload session or the bin retention window has passed.
  upload_expired:
    status: 410
    title: Upload expired
    meaning: The upload is finished or expired. Start it again.
  failed:
    status: 410
    title: Upload failed
    meaning: The upload failed. Start it again.
  file_too_large:
    status: 413
    title: File too large
    meaning: The file is larger than the plan allows.
  storage_full:
    status: 413
    title: Storage full
    meaning: There is not enough storage left. details.limit may carry the plan's limit in bytes.
  too_large:
    status: 413
    title: Too large
    meaning: A recursive listing covers more folders than one call can return. List a smaller folder.
  unprocessable_file:
    status: 422
    title: File could not be processed
    meaning: >-
      The PDF or file could not be changed or converted: it is damaged, password protected, a scan
      with no text for a text tool, has nothing to redact, or its pictures or tables could not be
      read. The message says which. details.not_found lists the texts that were not in the PDF.
  integrity_mismatch:
    status: 422
    title: Integrity check failed
    meaning: >-
      The stored file's SHA-256 differs from the one sent. details.expected and details.stored may
      carry both hashes.
  size_mismatch:
    status: 422
    title: Size mismatch
    meaning: The stored size differs from the size announced when the upload started.
  idempotency_in_progress:
    status: 409
    title: Request still running
    meaning: >-
      A request with the same Idempotency-Key has not finished. Wait Retry-After seconds and send it
      again; you get its answer.
  idempotency_key_reused:
    status: 422
    title: Idempotency key reused
    meaning: >-
      The Idempotency-Key was already used for a different request (another path, query, workspace
      or body). Use a new key.
  rate_limited:
    status: 429
    title: Rate limit exceeded
    meaning: >-
      Too many requests in this minute for this API key, or too many search and AI requests in this
      minute. Wait Retry-After seconds. The message says which limit was hit.
  quota_exceeded:
    status: 429
    title: Daily quota used up
    meaning: >-
      The organization's daily API quota is used up (it is shared by every API key and workspace of
      the organization). Retry-After is the number of seconds until it resets at midnight UTC. A
      plan with a higher quota raises it.
  ai_budget:
    status: 429
    title: AI credits used
    meaning: >-
      The organization's AI credits for the day, week or month are used (or its own AI key's
      budget). The message says when they reset; an owner can add credits in Billing.
  workspace_ai_off:
    status: 403
    title: AI is off for this workspace
    meaning: >-
      An owner or admin of the organization switched AI off for this workspace, so no AI endpoint
      (ask, search, read text) works there. They can turn it on from the workspace list or from
      Billing, Usage.
  slow_down:
    status: 429
    title: Asking too fast
    meaning: Too many questions in a short time. Wait a moment and ask again.
  ask_failed:
    status: 502
    title: The question could not be answered
    meaning: The AI provider could not answer this time, or the question was stopped. Retry.
  ask_timeout:
    status: 504
    title: The question took too long
    meaning: >-
      The answer was not finished in time and was stopped. Ask a narrower question, for example with
      folder set, or fewer files.
  ask_rate_limited:
    status: 429
    title: The AI is busy
    meaning: The AI provider asked us to slow down. Retry in a minute.
  ask_too_large:
    status: 413
    title: The files are too large to read at once
    meaning: >-
      The files the question needed are over what one answer can read. Ask about fewer or smaller
      files, or set folder.
  ask_unavailable:
    status: 503
    title: The AI is not available
    meaning: Tarkle's AI service cannot answer right now. Retry later.
  ask_cancelled:
    status: 499
    title: The question was cancelled
    meaning: The client closed the request before the answer was finished.
  too_many_uploads:
    status: 429
    title: Too many uploads
    meaning: Too many uploads are open at once. Finish or abort some first.
  transfer_too_large:
    status: 413
    title: Transfer too large
    meaning: >-
      The transfer's total size is larger than the plan's maximum transfer size. details.limit
      carries the limit in bytes.
  transfer_monthly_limit:
    status: 429
    title: Monthly transfer limit reached
    meaning: >-
      The plan's monthly transfer count has been reached. details.limit and details.currentUsage
      carry the numbers.
  file_not_found:
    status: 404
    title: File not found
    meaning: The file the new version belongs to does not exist any more.
  upload_not_found:
    status: 404
    title: Upload not found
    meaning: The version upload does not exist or was cleaned up. Start it again.
  version_unavailable:
    status: 404
    title: Version unavailable
    meaning: The version this upload was based on is no longer available.
  file_in_transfer:
    status: 409
    title: File is in a transfer
    meaning: >-
      A transfer uses this file. Confirm the transfer update in the app, or switch on automatic
      transfer updates in the workspace's file settings.
  upload_in_progress:
    status: 409
    title: Version upload in progress
    meaning: Someone else is already uploading a new version of this file. Retry shortly.
  current_version_changed:
    status: 409
    title: File changed meanwhile
    meaning: The file got another version while this upload was running. Upload again.
  storage_usage_unreadable:
    status: 409
    title: Storage usage unreadable
    meaning: Storage usage could not be verified, so nothing was saved. Retry.
  storage_limit_exceeded:
    status: 413
    title: Storage limit exceeded
    meaning: >-
      There is not enough storage for this version. Older versions count toward storage until they
      expire.
  version_failed:
    status: 500
    title: Version could not be saved
    meaning: The new version could not be saved. Retry; if it persists, contact support.
  server_error:
    status: 500
    title: Server error
    meaning: Something went wrong on our side. Retry; if it persists, contact support.
  storage_unavailable:
    status: 502
    title: Storage unavailable
    meaning: The storage backend failed. Nothing was created; retry.
  unavailable:
    status: 503
    title: Service unavailable
    meaning: The endpoint is switched off or the plan could not be confirmed. Retry later.
  entitlement_unresolved:
    status: 503
    title: Plan could not be resolved
    meaning: The plan could not be confirmed. Retry.
paths:
  /files/{id}:
    get:
      operationId: getFile
      summary: Get one file or folder, with its path and whether it is protected
      description: >-
        Returns one file or folder by id, with its absolute path and whether a protection rule
        applies to it (protected, protection_kind). A file id is digits, a folder id is a uuid.
        Needs files:read.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
      security:
        - bearer:
            - files:read
      x-required-scope: files:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryWithPath'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
```

# MCP Server

There's an MCP server at `https://project-03b42162.restlessdocs.com/mcp` exposing tools like `search_endpoints`, `get_endpoint`, and operation lookup. When you need specifics about an endpoint - parameters, status codes, examples - query the MCP server first; do not guess.

If the user has not yet connected the MCP server in their client, they can install it from the docs at `https://project-03b42162.restlessdocs.com`.
