Référence API (OpenAPI)

openapi: 3.0.3
info:
  title: APEX API — AI Intelligence for Developers
  version: 0.1.0
  description: |-
    APEX provides AI news intelligence: search, topic subscriptions, and daily briefings.

    ## Authentication
    
    All API requests require an API key via `Authorization: Bearer YOUR_KEY` header.
    
    ## Rate Limits
    
    - Free tier: 100 requests/hour
    - Pro tier: 1000 requests/hour
    
    ## Base URL
    
    Production: `https://apex.incwo.com/api`
    Development: `https://apex.incwo.com/api`
    
    ## Quickstart (2 minutes)
    
    ```bash
    # 1. Get your API key
    export APEX_KEY="your-key"
    
    # 2. Search for AI news
    curl -H "Authorization: Bearer $APEX_KEY" \
      "https://apex.incwo.com/api/search?q=machine%20learning&limit=5"
    
    # 3. Follow topics for briefings
    curl -X POST -H "Authorization: Bearer $APEX_KEY" \
      -H "Content-Type: application/json" \
      -d '{"topics":["ai","health"]}' \
      "https://apex.incwo.com/api/topics/follow"
    
    # 4. Get daily briefing
    curl -H "Authorization: Bearer $APEX_KEY" \
      "https://apex.incwo.com/api/brief?topics=ai,health"
    ```

servers:
  - url: https://apex.incwo.com/api
    description: Production API
  - url: https://apex.incwo.com/api
    description: Local development

paths:
  /search:
    get:
      summary: Search APEX news database
      operationId: searchNews
      parameters:
        - name: q
          in: query
          description: >-
            Free-text search query. Supports boolean operators `AND`/`OR`/`NOT`
            (and aliases `ET`/`OU`/`SANS`) with optional parentheses.
          required: false
          schema:
            type: string
          example: "(OpenAI OR Google) NOT Meta"
        - name: topics
          in: query
          description: Filter by topics (comma-separated)
          required: false
          schema:
            type: string
          example: "ai,health,finance"
        - name: from
          in: query
          description: Filter from date (ISO 8601)
          required: false
          schema:
            type: string
            format: date
          example: "2025-01-01"
        - name: to
          in: query
          description: Filter to date (ISO 8601)
          required: false
          schema:
            type: string
            format: date
          example: "2025-06-01"
        - name: limit
          in: query
          description: Max results (default: 20)
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
          example: 10
      responses:
        200:
          description: Successful search response
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  total:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsItem'
              example:
                query: "machine learning"
                total: 42
                results:
                  - id: "a1"
                    title: "New ML Framework Released"
                    summary: "A new machine learning framework simplifies model development..."
                    publishedAt: "2025-06-01T10:00:00Z"
                    source: "tech-crunch"
                    topics: ["ML", "python"]
                    confidence: 0.92
        401:
          description: Unauthorized - missing or invalid API key
        400:
          description: Bad request - invalid parameters
        429:
          description: Rate limit exceeded

  /topics/follow:
    post:
      summary: Subscribe to topics
      operationId: followTopics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                topics:
                  type: array
                  items:
                    type: string
                  description: List of topics to follow
                action:
                  type: string
                  enum: [follow, unfollow]
                  default: follow
              required:
                - topics
      responses:
        200:
          description: Topics subscribed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  following:
                    type: array
                    items:
                      type: string
              example:
                following: ["ai", "health", "finance"]
        401:
          description: Unauthorized

  /topics:
    get:
      summary: Get followed topics
      operationId: getFollowedTopics
      responses:
        200:
          description: List of followed topics
          content:
            application/json:
              schema:
                type: object
                properties:
                  topics:
                    type: object
                    additionalProperties:
                      type: string
                      format: date-time
              example:
                topics:
                  ai: "2025-06-01T10:00:00Z"
                  health: "2025-06-01T10:00:00Z"

  /brief:
    get:
      summary: Get daily briefing on topics
      operationId: getDailyBriefing
      parameters:
        - name: topics
          in: query
          description: Override followed topics (comma-separated)
          required: false
          schema:
            type: string
          example: "ai,health,research"
        - name: date
          in: query
          description: Date for briefing (default: today)
          required: false
          schema:
            type: string
            format: date
          example: "2025-06-01"
      responses:
        200:
          description: Daily briefing
          content:
            application/json:
              schema:
                type: object
                properties:
                  date:
                    type: string
                    format: date
                  topics:
                    type: array
                    items:
                      type: string
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsItem'
                  total:
                    type: integer

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    NewsItem:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        summary:
          type: string
        publishedAt:
          type: string
          format: date-time
        source:
          type: string
        topics:
          type: array
          items:
            type: string
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
      required:
        - id
        - title
        - summary
        - publishedAt

security:
  - bearerAuth: []