openapi: 3.1.0
info:
  title: addons-stremio.com Public Directory API
  version: 1.0.0
  description: Read-only access to approved public Stremio addon metadata. The directory does not host addon content.
  license:
    name: CC BY 4.0
    identifier: CC-BY-4.0
servers:
  - url: https://addons-stremio.com
paths:
  /api/v1/addons:
    get:
      operationId: searchStremioAddons
      summary: Search and filter approved Stremio addons
      parameters:
        - { name: q, in: query, schema: { type: string, maxLength: 160 } }
        - { name: category, in: query, schema: { type: string }, example: subtitles }
        - { name: language, in: query, schema: { type: string }, example: ro }
        - { name: type, in: query, schema: { type: string }, example: movie }
        - { name: status, in: query, schema: { type: string, enum: [online, degraded, offline] } }
        - { name: sort, in: query, schema: { type: string, enum: [recommended, stars, rating, installs, newest, updated, name] } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 50 } }
        - { name: offset, in: query, schema: { type: integer, minimum: 0, default: 0 } }
      responses:
        '200':
          description: A paginated public addon collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddonCollection'
  /api/v1/addons/{slug}:
    get:
      operationId: getStremioAddon
      summary: Get one approved addon by directory slug
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
        - name: format
          in: query
          schema: { type: string, enum: [json, markdown] }
      responses:
        '200':
          description: Public addon metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Addon' }
            text/markdown:
              schema: { type: string }
        '404': { description: Addon not found }
components:
  schemas:
    Addon:
      type: object
      required: [id, stremioId, slug, name, canonicalUrl, manifestUrl, types, categories, languages, health, community, createdAt, updatedAt]
      properties:
        id: { type: string, format: uuid }
        stremioId: { type: string }
        slug: { type: string }
        name: { type: string }
        description: { type: [string, 'null'] }
        version: { type: [string, 'null'] }
        canonicalUrl: { type: string, format: uri }
        manifestUrl: { type: string, format: uri }
        installUrl: { type: [string, 'null'] }
        configurationUrl: { type: [string, 'null'] }
        iconUrl: { type: [string, 'null'] }
        backgroundUrl: { type: [string, 'null'] }
        types: { type: array, items: { type: string } }
        categories: { type: array, items: { type: string } }
        languages: { type: array, items: { type: string } }
        resources: {}
        catalogs: {}
        health: { type: object }
        community: { type: object }
        promotion: { type: object }
        provenance: { type: object }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    AddonCollection:
      type: object
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/Addon' } }
        meta: { type: object }
