openapi: 3.1.0
info:
  title: VerseOS Developer API
  version: 1.0.0-private-beta
  description: |
    Private-beta contract for VerseOS asset discovery, rights discovery,
    licensing, payment verification, verification records, and x402 agent licensing.
servers:
  - url: http://localhost:3000
    description: Local development
security:
  - bearerAuth: []
paths:
  /v1/assets:
    get:
      summary: List public assets
      parameters:
        - { name: type, in: query, schema: { type: string } }
        - { name: universe, in: query, schema: { type: string } }
        - { name: verification_status, in: query, schema: { type: string } }
        - { name: q, in: query, schema: { type: string } }
        - { name: licensable, in: query, schema: { type: boolean } }
        - { name: page, in: query, schema: { type: integer, minimum: 1 } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }
      responses:
        '200': { description: Asset list }
    post:
      summary: Register an asset
      responses:
        '200': { description: Asset created }
        '201': { description: Asset created }
  /v1/assets/{id}:
    get:
      summary: Get an asset record
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200': { description: Asset record }
        '404': { description: Asset not found }
  /v1/assets/{id}/rights:
    get:
      summary: List available rights for a public asset
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200': { description: Rights list }
  /v1/rights:
    get:
      summary: Search available rights
      parameters:
        - { name: medium, in: query, schema: { type: string } }
        - { name: territory, in: query, schema: { type: string } }
        - { name: exclusivity, in: query, schema: { type: string } }
        - { name: template_key, in: query, schema: { type: string } }
        - { name: ai_usage, in: query, schema: { type: string } }
        - { name: derivative_works, in: query, schema: { type: string } }
        - { name: asset_type, in: query, schema: { type: string } }
        - { name: q, in: query, schema: { type: string } }
        - { name: min_price_usdc, in: query, schema: { type: number } }
        - { name: max_price_usdc, in: query, schema: { type: number } }
        - { name: page, in: query, schema: { type: integer, minimum: 1 } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }
      responses:
        '200': { description: Rights list }
  /v1/rights/{id}:
    get:
      summary: Get one available right
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200': { description: Right record }
        '404': { description: Right not found }
  /v1/license-intents:
    post:
      summary: Create a standard license purchase intent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [right_id]
              properties:
                right_id: { type: string, examples: [RGT-794B30A19A22] }
      responses:
        '200': { description: License intent created }
        '201': { description: License intent created }
        '409': { description: Purchase conflict }
  /v1/payments/verify:
    post:
      summary: Verify a Solana payment and issue the license
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [signature, license_intent_id]
              properties:
                signature: { type: string }
                license_intent_id: { type: string, examples: [INT-...] }
      responses:
        '200': { description: Payment verified / existing fulfillment returned }
        '201': { description: Payment verified and license issued }
        '400': { description: Payment invalid }
        '409': { description: Replay or fulfillment conflict }
  /v1/licenses/{id}:
    get:
      summary: Get a license
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200': { description: License record }
        '404': { description: License not found }
  /v1/verify/{id}:
    get:
      summary: Get a public verification record
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200': { description: Verification record }
        '404': { description: Record not publicly visible }
  /v1/agent-licenses:
    post:
      summary: Buy a license through x402
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string, maxLength: 200 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [right_id]
              properties:
                right_id: { type: string, examples: [RGT-794B30A19A22] }
      responses:
        '201':
          description: x402 payment settled and license issued
          headers:
            PAYMENT-RESPONSE:
              schema: { type: string }
        '402':
          description: x402 payment required or rejected
          headers:
            PAYMENT-REQUIRED:
              schema: { type: string }
        '409': { description: Idempotency, expiry, or right conflict }
        '502': { description: Facilitator/payment upstream unavailable }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: VerseOS API key
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema: { type: string }