openapi: 3.0.3
info:
  title: GlobalTenderCircle API
  description: |
    Planned public API for tender discovery and alerts. **Not yet live** — version with your deployment.
    Official source URLs remain the issuer's publication; this API aggregates metadata and links.
  version: 0.1.0
servers:
  - url: https://api.globaltendercircle.website/v1
    description: Planned production base URL
paths:
  /tenders:
    get:
      summary: Search canonical tenders
      operationId: listTenders
      parameters:
        - name: q
          in: query
          schema: { type: string }
        - name: country
          in: query
          schema: { type: string }
        - name: sector
          in: query
          schema: { type: string }
        - name: deadline_from
          in: query
          schema: { type: string, format: date-time }
        - name: deadline_to
          in: query
          schema: { type: string, format: date-time }
        - name: page
          in: query
          schema: { type: integer, minimum: 1 }
        - name: page_size
          in: query
          schema: { type: integer, maximum: 100 }
      responses:
        "200":
          description: Paginated tender list
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: { $ref: "#/components/schemas/Tender" }
                  next_cursor: { type: string, nullable: true }
        "401": { description: Unauthorized }
        "429": { description: Rate limited }
  /tenders/{id}:
    get:
      summary: Get one tender with source observations
      operationId: getTender
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Tender" }
        "404": { description: Not found }
components:
  schemas:
    SourceObservation:
      type: object
      properties:
        url: { type: string, format: uri }
        retrieved_at: { type: string, format: date-time }
        raw_ref: { type: string, nullable: true }
    Tender:
      type: object
      properties:
        id: { type: string }
        title: { type: string }
        summary: { type: string, nullable: true }
        buyer_name: { type: string, nullable: true }
        country: { type: string, nullable: true }
        published_at: { type: string, format: date-time, nullable: true }
        deadline_at: { type: string, format: date-time, nullable: true }
        source_observations:
          type: array
          items: { $ref: "#/components/schemas/SourceObservation" }
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
security:
  - bearerAuth: []