openapi: 3.1.0
info:
  title: Visitar Link API
  summary: Public catalog and authenticated link-management API for Visitar Link.
  description: "Visitar Link — Links curtos, claros e mensuráveis.\n\nPublic catalog (no key): GET /api/v1 and GET /api/v1/organization.\nAuthenticated link API: Authorization: Bearer vl_live_… on /api/v1/links.\nRate limit: 60 requests per minute per client on the catalog. Responses include RateLimit headers. A 429 includes Retry-After.\n\nHuman docs: https://visitarlink.com/docs\nDeveloper resources: https://visitarlink.com/developers\nAgent index: https://visitarlink.com/llms.txt\nWhen to use: https://visitarlink.com/agents.md"
  version: 1.0.0
  contact:
    name: Visitar Link by UNFLD
    email: hello@unfld.com.br
    url: "https://visitarlink.com"
  license:
    name: Visitar Link terms
    url: "https://visitarlink.com/termos"
servers:
  - url: "https://visitarlink.com"
        description: Production
tags:
  - name: Discovery
        description: Index and machine documents.
  - name: Organization
        description: Legal identity and contact.
  - name: Links
        description: Create and manage short links. Requires an API key.
paths:
  "/api/v1":
    get:
      operationId: getCatalogIndex
      tags:
        - Discovery
      summary: Catalog index
      description: "Start here. Returns documentation links, authentication notes, and the list of catalog collections. No API key."
      responses:
        "200":
          description: Catalog index.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CatalogIndex"
        "429":
          description: Rate limit exceeded. Wait Retry-After seconds.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v1/organization":
    get:
      operationId: getOrganization
      tags:
        - Organization
      summary: Company identity
      description: "Legal name, CNPJ, São Paulo address, and contacts for UNFOLDING THE FUTURE LTDA trading as UNFLD, operator of Visitar Link."
      responses:
        "200":
          description: Organization record.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Organization"
        "429":
          description: Rate limit exceeded.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/health":
    get:
      operationId: getHealth
      tags:
        - Discovery
      summary: Service health
      description: Liveness of Visitar Link and its database.
      responses:
        "200":
          description: Healthy.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Health"
        "503":
          description: Unhealthy.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Health"
  "/api/v1/links":
    get:
      operationId: listLinks
      tags:
        - Links
      summary: List short links
      description: List short links in the workspace bound to the API key.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Link list.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/LinkList"
        "401":
          description: Missing or invalid API key.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limit exceeded.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    post:
      operationId: createLink
      tags:
        - Links
      summary: Create a short link
      description: "Shorten a destination URL, or create a TJRS case-tracking page with kind=tjrs. Optionally choose a slug. Returns the stored link including the public short URL. The access key is never returned."
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateLinkRequest"
      responses:
        "201":
          description: Link created.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/LinkEnvelope"
        "400":
          description: Validation failed.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "401":
          description: Missing or invalid API key.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limit exceeded.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v1/links/{id}":
    parameters:
      - name: id
                in: path
                required: true
                description: Link id (lnk_…).
                schema:
                  type: string
                  examples:
                    - lnk_01example
    get:
      operationId: getLink
      tags:
        - Links
      summary: Get one short link
      description: Fetch a single short link by id in the caller's workspace.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Link.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/LinkEnvelope"
        "401":
          description: Missing or invalid API key.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "404":
          description: Link not found in this workspace.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      operationId: updateLink
      tags:
        - Links
      summary: Update a short link
      description: "Change destination, title, or status (active | paused)."
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpdateLinkRequest"
      responses:
        "200":
          description: Updated link.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/LinkEnvelope"
        "400":
          description: Validation failed.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "401":
          description: Missing or invalid API key.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "404":
          description: Link not found.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    delete:
      operationId: deleteLink
      tags:
        - Links
      summary: Delete a short link
      description: Permanently delete a short link. The slug becomes available again.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Deleted.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Ok"
        "401":
          description: Missing or invalid API key.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "404":
          description: Link not found.
          headers:
            RateLimit:
              description: "IETF combined quota: limit, remaining, reset (seconds)."
              schema:
                type: string
                examples:
                  - "limit=60, remaining=59, reset=60"
            RateLimit-Policy:
              description: Quota policy. 60 requests per 60-second window on the public catalog.
              schema:
                type: string
                examples:
                  - 60;w=60
            RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Limit:
              schema:
                type: integer
                examples:
                  - 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                examples:
                  - 59
            X-RateLimit-Reset:
              schema:
                type: integer
                examples:
                  - 60
            API-Version:
              schema:
                type: string
                examples:
                  - 1
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: vl_live
      description: "API key from the Visitar Link dashboard. Header: Authorization: Bearer vl_live_…"
  schemas:
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              description: "Stable machine code, e.g. not_found."
            message:
              type: string
            hint:
              type: string
              description: How an agent should recover.
    CatalogIndex:
      type: object
      additionalProperties: false
      required:
        - name
        - version
        - description
        - documentation
        - openapi
        - llms
        - authentication
        - rateLimit
        - links
      properties:
        name:
          type: string
        version:
          type: string
        description:
          type: string
        documentation:
          type: string
          format: uri
        developers:
          type: string
          format: uri
        openapi:
          type: string
          format: uri
        openapiYaml:
          type: string
          format: uri
        llms:
          type: string
          format: uri
        agentInstructions:
          type: string
          format: uri
        authentication:
          type: string
        rateLimit:
          type: object
          required:
            - limit
            - windowSeconds
            - policy
          properties:
            limit:
              type: integer
            windowSeconds:
              type: integer
            policy:
              type: string
            note:
              type: string
        versioning:
          type: object
          additionalProperties: true
        links:
          type: object
          additionalProperties:
            type: string
            format: uri
    Organization:
      type: object
      additionalProperties: false
      required:
        - product
        - companyName
        - legalName
        - cnpj
        - address
        - contacts
      properties:
        product:
          type: string
        domain:
          type: string
        companyName:
          type: string
        legalName:
          type: string
        tradingName:
          type: string
        cnpj:
          type: string
        url:
          type: string
          format: uri
        productUrl:
          type: string
          format: uri
        tagline:
          type: string
        address:
          type: object
          additionalProperties: true
        contacts:
          type: object
          additionalProperties: true
    Health:
      type: object
      required:
        - ok
        - service
      properties:
        ok:
          type: boolean
        db:
          type: boolean
        service:
          type: string
    CreateLinkRequest:
      type: object
      additionalProperties: false
      properties:
        destination:
          type: string
          format: uri
          description: Absolute http(s) URL to redirect to. Required unless kind is tjrs.
        slug:
          type: string
          description: "Optional custom slug. Lowercase letters, numbers, hyphen."
        title:
          type: string
        kind:
          type: string
          enum:
            - redirect
            - tjrs
          description: redirect (default) or tjrs for a TJRS case-tracking page.
        tjrsNumero:
          type: string
          description: CNJ number. Required when kind is tjrs. Tribunal must be 21 (TJRS).
        tjrsChave:
          type: string
          description: TJRS access key. Stored server-side only; never returned on the public page.
    UpdateLinkRequest:
      type: object
      additionalProperties: false
      properties:
        destination:
          type: string
          format: uri
        title:
          type: string
        status:
          type: string
          enum:
            - active
            - paused
    LinkEnvelope:
      type: object
      required:
        - link
      properties:
        link:
          "$ref": "#/components/schemas/Link"
    LinkList:
      type: array
      items:
        "$ref": "#/components/schemas/Link"
    Link:
      type: object
      additionalProperties: true
      required:
        - id
        - slug
        - destination
      properties:
        id:
          type: string
        slug:
          type: string
        destination:
          type: string
          format: uri
        title:
          type:
            - string
            - null
        shortUrl:
          type: string
          format: uri
        status:
          type: string
        kind:
          type: string
          enum:
            - redirect
            - tjrs
        tjrsNumero:
          type:
            - string
            - null
    Ok:
      type: object
      required:
        - ok
      properties:
        ok:
          type: boolean