ydb-qdrant-tech Pets API

openapi: 3.2.0
info:
  title: Codex Pets API
  version: 1.0.0
  description: 'Browse, preview, upload, and download community-made animated pet packs for Codex. This OpenAPI document describes version 1 of the public agent/developer contract subset: approved registry data, MCP discovery, markdown discovery docs, pricing and terms discovery, and public submission workflows. Existing unversioned URLs are stable v1 endpoints. Additive changes may appear without notice; breaking public-agent contract changes require a new path or a published deprecation notice. Public metric mutation and download redirect routes are intentionally outside this contract.'
  contact:
    name: Codex Pets
    url: https://pets.ydb-qdrant.tech/about
servers:
- url: https://pets.ydb-qdrant.tech
tags:
- name: Pets
  description: Approved public Codex pet registry data.
paths:
  /api/manifest:
    get:
      operationId: getManifest
      tags:
      - Pets
      summary: List approved Codex pets for agents and the CLI
      security: []
      responses:
        '200':
          description: Successful JSON response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManifestResponse'
  /api/manifest.toon:
    get:
      operationId: getManifestToon
      tags:
      - Pets
      summary: List approved Codex pets as TOON
      security: []
      responses:
        '200':
          description: Successful text response.
          content:
            text/toon:
              schema:
                type: string
  /api/pets:
    get:
      operationId: searchPets
      tags:
      - Pets
      summary: Search approved Codex pets
      description: Returns approved pets only. Private contact fields are never included. Pagination metadata is always included. Without page or pageSize, returns the first page of up to 200 pets with the full filtered count in pagination.totalItems.
      security: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Search text matched against pet name, description, and tags.
      - name: kind
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - creature
          - object
          - character
        description: Filter by pet kind. Defaults to all.
      - name: tags
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated tag filters.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        description: 1-based result page. Pagination metadata is always included. Pass the returned pagination.pageSize when requesting the next page.
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
        description: Number of pets per page. Defaults to 24 when page is supplied without pageSize; requests without both parameters use 200. Pass the returned pagination.pageSize when requesting the next page.
      responses:
        '200':
          description: Successful JSON response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PetsResponse'
        '400':
          description: Request failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/pets.toon:
    get:
      operationId: searchPetsToon
      tags:
      - Pets
      summary: Search approved Codex pets as TOON
      security: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Search text matched against pet name, description, and tags.
      - name: kind
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - creature
          - object
          - character
        description: Filter by pet kind. Defaults to all.
      - name: tags
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated tag filters.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        description: 1-based result page. Pagination metadata is always included. Pass the returned pagination.pageSize when requesting the next page.
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
        description: Number of pets per page. Defaults to 24 when page is supplied without pageSize; requests without both parameters use 200. Pass the returned pagination.pageSize when requesting the next page.
      responses:
        '200':
          description: Successful text response.
          content:
            text/toon:
              schema:
                type: string
        '400':
          description: Successful text response.
          content:
            text/toon:
              schema:
                type: string
  /api/pets/{slug}:
    get:
      operationId: getPet
      tags:
      - Pets
      summary: Get one approved Codex pet
      security: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{0,63}$
        description: Approved pet slug.
      responses:
        '200':
          description: Successful JSON response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PetDetailResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/pets/{slug}.toon:
    get:
      operationId: getPetToon
      tags:
      - Pets
      summary: Get one approved Codex pet as TOON
      security: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{0,63}$
        description: Approved pet slug.
      responses:
        '200':
          description: Successful text response.
          content:
            text/toon:
              schema:
                type: string
        '404':
          description: Successful text response.
          content:
            text/toon:
              schema:
                type: string
  /api/tags:
    get:
      operationId: getTags
      tags:
      - Pets
      summary: List approved pet tag counts
      security: []
      responses:
        '200':
          description: Successful JSON response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagsResponse'
  /api/tags.toon:
    get:
      operationId: getTagsToon
      tags:
      - Pets
      summary: List approved pet tag counts as TOON
      security: []
      responses:
        '200':
          description: Successful text response.
          content:
            text/toon:
              schema:
                type: string
  /api/pets/{slug}/share:
    get:
      operationId: getPetShareSnippets
      tags:
      - Pets
      summary: Get share snippets for an approved Codex pet
      security: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{0,63}$
        description: Approved pet slug.
      responses:
        '200':
          description: Successful JSON response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PetShareResponse'
        '400':
          description: Request failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/pets/{slug}/install:
    get:
      operationId: getPetInstallInstructions
      tags:
      - Pets
      summary: Get install instructions for an approved Codex pet
      description: Read-only install instruction endpoint. GET does not increment install counters.
      security: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{0,63}$
        description: Approved pet slug.
      responses:
        '200':
          description: Successful JSON response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PetInstallResponse'
        '400':
          description: Request failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ManifestResponse:
      type: object
      required:
      - generatedAt
      - total
      - pets
      properties:
        generatedAt:
          type: string
          format: date-time
        total:
          type: integer
          minimum: 0
        pets:
          type: array
          items:
            $ref: '#/components/schemas/ManifestPet'
    PetsResponse:
      type: object
      required:
      - total
      - pets
      - pagination
      properties:
        total:
          type: integer
          minimum: 0
          description: Number of pets in this response. pagination.totalItems is the full filtered count.
        pets:
          type: array
          items:
            $ref: '#/components/schemas/PublicPet'
        pagination:
          $ref: '#/components/schemas/PetsPagination'
    PublicPet:
      type: object
      required:
      - id
      - slug
      - displayName
      - description
      - spritesheetUrl
      - petJsonUrl
      - zipUrl
      - spritesheetExt
      - kind
      - tags
      - status
      - createdAt
      - downloadCount
      - installCount
      - likeCount
      properties:
        id:
          type: string
        slug:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{0,63}$
        displayName:
          type: string
        description:
          type: string
        spritesheetUrl:
          type: string
        petJsonUrl:
          type: string
        zipUrl:
          type: string
        spritesheetExt:
          type: string
          enum:
          - webp
          - png
        kind:
          type: string
          enum:
          - creature
          - object
          - character
          default: creature
        tags:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - approved
        ownerName:
          type:
          - string
          - 'null'
        ownerProfileSlug:
          type:
          - string
          - 'null'
        ownerProfileUrl:
          type:
          - string
          - 'null'
        ownerAvatarUrl:
          type:
          - string
          - 'null'
        publicAuthorEmail:
          type:
          - string
          - 'null'
          format: email
        createdAt:
          type: string
          format: date-time
        approvedAt:
          type:
          - string
          - 'null'
          format: date-time
        downloadCount:
          type: integer
          minimum: 0
        installCount:
          type: integer
          minimum: 0
        likeCount:
          type: integer
          minimum: 0
    TagsResponse:
      type: object
      required:
      - generatedAt
      - total
      - tags
      properties:
        generatedAt:
          type: string
          format: date-time
        total:
          type: integer
          minimum: 0
        tags:
          type: array
          items:
            type: object
            required:
            - name
            - count
            properties:
              name:
                type: string
              count:
                type: integer
                minimum: 1
    PetDetailResponse:
      type: object
      required:
      - pet
      properties:
        pet:
          $ref: '#/components/schemas/PublicPet'
    PetsPagination:
      type: object
      required:
      - page
      - pageSize
      - totalItems
      - totalPages
      - hasNextPage
      properties:
        page:
          type: integer
          minimum: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 200
        totalItems:
          type: integer
          minimum: 0
        totalPages:
          type: integer
          minimum: 0
        hasNextPage:
          type: boolean
    PetInstallResponse:
      type: object
      additionalProperties: true
    ManifestPet:
      type: object
      required:
      - slug
      - displayName
      - description
      - kind
      - tags
      - pageUrl
      - spritesheetUrl
      - petJsonUrl
      - zipUrl
      - installCommand
      - createdAt
      properties:
        slug:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{0,63}$
        displayName:
          type: string
        description:
          type: string
        kind:
          type: string
          enum:
          - creature
          - object
          - character
          default: creature
        tags:
          type: array
          items:
            type: string
        submittedBy:
          type:
          - string
          - 'null'
        submittedByEmail:
          type:
          - string
          - 'null'
          format: email
        submittedByUrl:
          type:
          - string
          - 'null'
        submittedByAvatarUrl:
          type:
          - string
          - 'null'
        pageUrl:
          type: string
          format: uri
        spritesheetUrl:
          type: string
        petJsonUrl:
          type: string
        zipUrl:
          type: string
        installCommand:
          type: string
        createdAt:
          type: string
          format: date-time
        approvedAt:
          type:
          - string
          - 'null'
          format: date-time
    PetShareResponse:
      type: object
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        message:
          type: string
        hint:
          type: string
        field:
          type: string
      required:
      - error
      - code
      - message
      additionalProperties: true
  securitySchemes:
    AppSessionCookie:
      type: apiKey
      in: cookie
      name: codex_pets_session
      description: Optional app-session cookie used by browser account flows. Public read endpoints do not require it.
    ProxyBasic:
      type: http
      scheme: basic
      description: Deployment mode for trusted reverse proxies. Public agent endpoints are designed to be readable without credentials.