> ## 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.

# Create a new article

> Create a new article. Currently requires admin API key for access.
- **Admin API keys**: Must provide account_id in request body, can create articles for any account

**Note**: In the future, we plan to implement scoped API keys that will allow account-specific keys to create articles for their own accounts.


<Warning>
  **Admin API Key Required** - This endpoint currently requires an admin API key for access. Admin keys can create articles for any account by specifying the `account_id` in the request body.
</Warning>

<Info>
  **Future Enhancement** - We're planning to implement scoped API keys with different permission levels (read-only, read-write, etc.). Once this is available, account-specific API keys will be able to create articles for their own accounts without requiring admin privileges.
</Info>


## OpenAPI

````yaml post /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:
    post:
      tags:
        - Articles
      summary: Create a new article
      description: >
        Create a new article. Currently requires admin API key for access.

        - **Admin API keys**: Must provide account_id in request body, can
        create articles for any account


        **Note**: In the future, we plan to implement scoped API keys that will
        allow account-specific keys to create articles for their own accounts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - account_id
                - customer_avatar_id
                - category
                - title
                - content
              properties:
                account_id:
                  type: string
                  format: uuid
                  description: >-
                    Account UUID (required - specifies which account to create
                    the article for)
                customer_avatar_id:
                  type: string
                  format: uuid
                  description: >-
                    Customer avatar UUID (required - links article to specific
                    customer persona)
                category:
                  type: string
                  enum:
                    - opinion_piece
                    - industry_forecast
                    - how_to_guide
                    - comparison
                    - deep_research
                    - checklist
                    - roundup
                  description: Article category for content organization
                title:
                  type: string
                  minLength: 1
                  maxLength: 500
                content:
                  type: string
                  minLength: 1
                meta_description:
                  type: string
                  maxLength: 500
                tags:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 50
                  maxItems: 20
                  default: []
                status:
                  type: string
                  enum:
                    - draft
                    - published
                    - archived
                    - deleted
                  default: published
                hero_image_url:
                  type: string
                  format: uri
                publish_date:
                  type: string
                  format: date-time
      responses:
        '200':
          description: Article created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Article'
        '400':
          description: Bad request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Admin API key required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - AdminApiKey: []
components:
  schemas:
    Article:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
          example: How to Optimize Your Website for SEO
        slug:
          type: string
          example: how-to-optimize-website-seo
        content:
          type: string
          description: HTML content of the article
        meta_description:
          type: string
          maxLength: 500
          nullable: true
        hero_image_url:
          type: string
          format: uri
          nullable: true
        category:
          type: string
          enum:
            - opinion_piece
            - industry_forecast
            - how_to_guide
            - comparison
            - deep_research
            - checklist
            - roundup
          example: how_to_guide
        customer_avatar_id:
          type: string
          format: uuid
          description: Customer avatar this article is targeting
        tags:
          type: array
          items:
            type: string
          example:
            - SEO
            - Digital Marketing
            - Website Optimization
        status:
          type: string
          enum:
            - draft
            - published
            - archived
            - deleted
          example: published
        publish_date:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        account_id:
          type: string
          format: uuid
        _links:
          type: object
          properties:
            self:
              type: string
              format: uri
            account:
              type: string
              format: uri
            public_url:
              type: string
              format: uri
              nullable: true
    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

````