> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsonic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List articles

> Retrieve a paginated list of articles with filtering and search options.
The articles returned depend on the authentication used:

**Authenticated Access:**
- **Admin API keys**: Returns articles from all accounts across the system
- **Account API keys**: Returns articles only from the account that owns the key

**Public Access** (from valid domains):
- **No authentication required** when accessing from verified domains (*.localhost, *.suprsonic.blog, *.suprsonic.app, or verified custom domains)
- Returns only **published articles** from the domain-associated account
- Status filtering is ignored for public access (always returns published only)




## OpenAPI

````yaml get /api/v1/articles
openapi: 3.1.0
info:
  title: SuprSonic API
  version: 1.0.0
  description: API for autonomous content generation and blog management
  contact:
    name: SuprSonic API Support
    url: https://www.suprsonic.com/support
    email: support@suprsonic.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://www.suprsonic.com
    description: Production server
  - url: http://localhost:3000
    description: Development server
security: []
tags: []
paths:
  /api/v1/articles:
    get:
      tags:
        - Articles
      summary: List articles
      description: >
        Retrieve a paginated list of articles with filtering and search options.

        The articles returned depend on the authentication used:


        **Authenticated Access:**

        - **Admin API keys**: Returns articles from all accounts across the
        system

        - **Account API keys**: Returns articles only from the account that owns
        the key


        **Public Access** (from valid domains):

        - **No authentication required** when accessing from verified domains
        (*.localhost, *.suprsonic.blog, *.suprsonic.app, or verified custom
        domains)

        - Returns only **published articles** from the domain-associated account

        - Status filtering is ignored for public access (always returns
        published only)
      parameters:
        - in: query
          name: q
          schema:
            type: string
          description: Search articles by title or meta description
        - in: query
          name: tags
          schema:
            type: string
          description: Filter by tags (comma-separated)
          example: SEO,Marketing,Content
        - in: query
          name: category
          schema:
            type: string
            enum:
              - opinion_piece
              - industry_forecast
              - how_to_guide
              - comparison
              - deep_research
              - checklist
              - roundup
          description: Filter by article category
        - in: query
          name: status
          schema:
            type: string
            enum:
              - draft
              - published
              - archived
              - deleted
          description: Filter by article status
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of items per page
      responses:
        '200':
          description: Successfully retrieved articles
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        account_id:
                          type: string
                          format: uuid
                        customer_avatar_id:
                          type: string
                          format: uuid
                        category:
                          type: string
                          enum:
                            - opinion_piece
                            - industry_forecast
                            - how_to_guide
                            - comparison
                            - deep_research
                            - checklist
                            - roundup
                        title:
                          type: string
                        slug:
                          type: string
                        meta_description:
                          type: string
                          nullable: true
                        hero_image_url:
                          type: string
                          format: uri
                          nullable: true
                        tags:
                          type: array
                          items:
                            type: string
                        status:
                          type: string
                          enum:
                            - draft
                            - published
                            - archived
                            - deleted
                        publish_date:
                          type: string
                          format: date-time
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                        _links:
                          type: object
                          properties:
                            self:
                              type: string
                              format: uri
                            account:
                              type: string
                              format: uri
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - AdminApiKey: []
        - AccountApiKey: []
        - {}
components:
  schemas:
    PaginationMeta:
      type: object
      properties:
        pagination:
          type: object
          properties:
            page:
              type: integer
              example: 1
            limit:
              type: integer
              example: 20
            total:
              type: integer
              example: 100
            totalPages:
              type: integer
              example: 5
            hasNext:
              type: boolean
              example: true
            hasPrev:
              type: boolean
              example: false
        links:
          type: object
          properties:
            self:
              type: string
              example: /api/v1/articles?page=1
            next:
              type: string
              example: /api/v1/articles?page=2
            prev:
              type: string
              example: null
            first:
              type: string
              example: /api/v1/articles?page=1
            last:
              type: string
              example: /api/v1/articles?page=5
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Invalid request data
            details:
              type: object
  securitySchemes:
    AdminApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Admin API key for managing accounts and creating content
    AccountApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Account-specific API key for accessing account data

````