openapi: 3.1.0
info:
  title: ArticlesQ API
  version: 1.0.0
  description: >-
    Read your generated articles programmatically — power blogs, mobile apps, or
    any frontend with a single HTTPS call. Push articles you generated yourself
    with `POST /articles` and let ArticlesQ host them (handy when you want
    backlinks-exchange participation but bring your own writer).


    ## Quick start


    1. Open **Settings → Integrations & API** for your project in the ArticlesQ
    dashboard and create an API key.

    2. Pass it as a Bearer token: `Authorization: Bearer aq_live_...`

    3. List your articles: `GET /articles`

    4. Fetch a single article: `GET /articles/{slug}`

    5. Push your own: `POST /articles` with markdown content

    6. Update an article: `PATCH /articles/{slug}` (e.g. tweak the meta
    description), and publish it with `POST /articles/{slug}/status` (needs the
    `articles:publish` scope)

    7. Generate its cover and in-content images: `POST /articles/{slug}/images`
    (read `GET /image-settings` first to see the style and brand notes your
    prompts are combined with)


    ## Key concepts


    - Each API key is scoped to exactly one **project**. The same key can never
    see another project's articles.

    - Pagination uses simple `page` + `pageSize` query params. Default page size
    is 20, max is 100.

    - The article `content` field is markdown.

    - Slugs are unique within a project — POST returns `409 slug_conflict` if
    you try to reuse one.
servers:
  - url: https://articlesq.com/api/v1
    description: Production
tags:
  - name: Articles
    description: Read articles generated for the project this API key is scoped to.
  - name: Images
    description: The style, logo, character and brand notes ArticlesQ adds to every
      image it generates for the project.
  - name: Webhooks
    description: Events ArticlesQ sends to your endpoint, signed with the Standard
      Webhooks scheme, so a static site can revalidate the moment an article
      changes instead of waiting for a redeploy. Add an endpoint under
      **Settings → Integrations & API → Webhooks**; the signing secret is issued
      per endpoint.
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: "ArticlesQ API key sent as `Authorization: Bearer aq_live_...`.
        Each key is scoped to a single project."
  schemas:
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            title:
              type: string
              example: Unauthorized
            status:
              type: integer
              example: 401
            code:
              $ref: "#/components/schemas/ApiErrorCode"
            message:
              type: string
              example: Missing Authorization header
            instance:
              type: string
              example: /api/v1/articles
            details:
              type: object
              additionalProperties:
                type: object
          required:
            - title
            - status
            - code
            - message
      required:
        - error
    ApiErrorCode:
      type: string
      enum:
        - missing_auth
        - invalid_auth_format
        - invalid_api_key
        - api_key_expired
        - insufficient_scope
        - forbidden
        - not_found
        - route_not_found
        - validation_failed
        - slug_conflict
        - internal_error
      example: missing_auth
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
          description: Current page number (starting from 1).
        limit:
          type: integer
          example: 20
          description: Maximum number of items returned per page.
        total:
          type: integer
          example: 100
          description: Total number of matching items.
        totalPages:
          type: integer
          example: 5
          description: Total number of pages for the current limit.
        hasNext:
          type: boolean
          example: true
          description: Whether another page exists after the current one.
        hasPrev:
          type: boolean
          example: false
          description: Whether another page exists before the current one.
      required:
        - page
        - limit
        - total
        - totalPages
        - hasNext
        - hasPrev
    FaqItem:
      type: object
      properties:
        q:
          type: string
          example: What is the best CRM for early-stage startups?
          description: The question. Plain text, no markdown.
        a:
          type: string
          example: For teams under 20 people, lightweight tools like HubSpot Free or Folk
            are usually a better fit than enterprise CRMs.
          description: The answer. Plain text, no markdown.
      required:
        - q
        - a
    Article:
      type: object
      properties:
        id:
          type: string
          example: clx1abc234...
        slug:
          type: string
          example: best-crm-for-startups
        title:
          type: string
          example: Best CRM for Startups in 2026
        keyword:
          type: string
          example: best crm for startups
        metaDescription:
          type:
            - string
            - "null"
          example: A practical guide to choosing the right CRM when you're under 50
            employees.
        content:
          type: string
          description: Markdown body of the article.
          example: |-
            # Introduction

            If you're a startup founder...
        coverImage:
          type:
            - string
            - "null"
          description: Public URL of the generated cover image. Null while pending or if
            image generation failed.
          example: https://cdn.articlesq.com/images/proj_abc/best-crm-for-startups/cover.jpeg
        faq:
          type: array
          items:
            $ref: "#/components/schemas/FaqItem"
          description: Structured FAQ as plain-text Q/A pairs. Empty array when the
            article has no FAQ. By default the project also appends this FAQ as
            markdown to `content`; toggle `inlineFaqInContent` on the project
            (or pass `?inlineFaq=false`) to receive `content` without the FAQ
            section.
        status:
          $ref: "#/components/schemas/ArticleStatus"
        datePublished:
          type:
            - string
            - "null"
          example: 2026-05-23T00:00:00.000Z
          description: Public publish date (schema.org `datePublished`) as an ISO 8601
            string. Null when no specific date is set. Editable from the
            dashboard.
        dateModified:
          type:
            - string
            - "null"
          example: 2026-06-01T00:00:00.000Z
          description: Last meaningful content update (schema.org `dateModified`) as an
            ISO 8601 string. Stamped automatically when a published article's
            content changes, and overridable from the dashboard for imported
            content. Null until either happens.
      required:
        - id
        - slug
        - title
        - keyword
        - metaDescription
        - content
        - coverImage
        - faq
        - status
        - datePublished
        - dateModified
    ArticleStatus:
      type: string
      enum:
        - draft
        - published
    ListArticlesResponse:
      type: object
      properties:
        articles:
          type: array
          items:
            $ref: "#/components/schemas/Article"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - articles
        - pagination
    ArticleResponse:
      type: object
      properties:
        article:
          $ref: "#/components/schemas/Article"
      required:
        - article
    CreateArticleBody:
      type: object
      properties:
        slug:
          type: string
          minLength: 1
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          example: best-crm-for-startups
          description: URL slug. Must be lowercase kebab-case and unique within the project.
        title:
          type: string
          minLength: 1
          example: Best CRM for Startups in 2026
          description: Article title — also used as the SEO title tag.
        keyword:
          type: string
          minLength: 1
          example: best crm for startups
          description: Primary keyword the article targets.
        content:
          type: string
          default: ""
          example: |-
            # Introduction

            If you're a startup founder...
          description: Markdown body of the article. Defaults to an empty string when
            omitted — useful when creating a stub to fill in later.
        metaDescription:
          type: string
          example: A practical guide to choosing the right CRM when you're under 50
            employees.
          description: SEO meta description, recommended < 155 characters.
        status:
          type: string
          enum:
            - draft
            - published
          example: draft
          description: Defaults to `draft`. Creating an article as `published` needs the
            `articles:publish` scope.
        datePublished:
          type:
            - string
            - "null"
          format: date-time
          example: 2026-11-03T09:00:00Z
          description: Public publish date (schema.org `datePublished`) as an ISO 8601
            date-time. Can be set on a draft and is kept when the article is
            published, so you can back-date imported or scheduled content.
            `null` clears it. When it is not set, the date of the first publish
            is used.
        faq:
          type: array
          items:
            $ref: "#/components/schemas/FaqItem"
          description: Structured FAQ as plain-text Q/A pairs. Server trims whitespace,
            drops fully-empty pairs, and rejects half-filled ones (only `q` or
            only `a`).
          example:
            - q: What is the best CRM for early-stage startups?
              a: For teams under 20 people, lightweight tools like HubSpot Free or Folk are
                usually a better fit than enterprise CRMs.
      required:
        - slug
        - title
        - keyword
    UpdateArticleBody:
      type: object
      properties:
        title:
          type: string
          example: 10 Link Building Strategies That Actually Work
          description: Article title. Empty strings are rejected.
        slug:
          type: string
          example: link-building-strategies
          description: URL-friendly slug. Empty strings are rejected. Must be unique
            within the project. Can only be changed while the article is in
            draft status.
        content:
          type: string
          example: |-
            # Introduction

            Updated body...
          description: New markdown body. Empty strings are rejected — you can clear other
            fields, but the article body must stay non-empty.
        metaDescription:
          type: string
          example: Learn proven link building strategies to boost your domain authority
            and organic traffic.
          description: SEO meta description, recommended < 155 characters.
        datePublished:
          type:
            - string
            - "null"
          format: date-time
          example: 2026-11-03T09:00:00Z
          description: Public publish date (schema.org `datePublished`) as an ISO 8601
            date-time. Can be set on a draft and is kept when the article is
            published, so you can back-date imported or scheduled content.
            `null` clears it. When it is not set, the date of the first publish
            is used.
        faq:
          type: array
          items:
            $ref: "#/components/schemas/FaqItem"
          description: Replace the structured FAQ. Server trims whitespace, drops
            fully-empty pairs, rejects half-filled ones. Pass `[]` to remove all
            items. Omit to leave it unchanged.
      additionalProperties: false
    SetArticleStatusBody:
      type: object
      properties:
        status:
          allOf:
            - $ref: "#/components/schemas/ArticleStatus"
            - description: "`published` makes the article public and sends
                `article.published`. `draft` takes it out of the public API and
                sends `article.unpublished`. The first publish sets
                `datePublished` when it is still empty."
              example: published
      required:
        - status
      additionalProperties: false
    GenerateArticleImagesBody:
      type: object
      properties:
        cover:
          $ref: "#/components/schemas/CoverImagePrompt"
        inline:
          type: array
          items:
            $ref: "#/components/schemas/InlineImagePrompt"
          maxItems: 10
          description: In-content images (16:9). Each one replaces its `{{IMAGE_N}}`
            marker in the article content with the generated image.
      additionalProperties: false
    CoverImagePrompt:
      type: object
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 4000
          description: "What the image shows: subject, action, setting, composition, and
            where the logo or character sits if you want a specific spot. The
            project's image style, its logo and character references, the
            placement rules and the project's brand notes are added to this
            prompt automatically, so describe the scene only."
          example: A developer at a standing desk in a bright studio, typing a request to
            an AI coding agent in a terminal. Next to it, a phone shows an
            Instagram post going live. The brand logo is on the developer's
            laptop lid.
        alt:
          type: string
          minLength: 1
          maxLength: 300
          description: Alt text for the image. Also used to name the stored file, so write
            it the way someone would search for it.
          example: instagram mcp server posting from claude code
        branding:
          type: boolean
          description: Set to `false` to leave the logo and character out of this image
            (e.g. a clean diagram). Defaults to the project's image settings.
      required:
        - prompt
        - alt
      description: Cover image (16:9). Replaces the current cover when the article
        already has one; the previous cover is kept in the article's image
        gallery.
    InlineImagePrompt:
      type: object
      properties:
        id:
          type: string
          pattern: ^IMAGE_[1-9][0-9]?$
          description: 'Marker this image replaces. Put `{{IMAGE_1}}` on its own line in
            the article content where the image belongs, then send `id:
            "IMAGE_1"`.'
          example: IMAGE_1
        prompt:
          type: string
          minLength: 1
          maxLength: 4000
          description: "What the image shows: subject, action, setting, composition, and
            where the logo or character sits if you want a specific spot. The
            project's image style, its logo and character references, the
            placement rules and the project's brand notes are added to this
            prompt automatically, so describe the scene only."
          example: A developer at a standing desk in a bright studio, typing a request to
            an AI coding agent in a terminal. Next to it, a phone shows an
            Instagram post going live. The brand logo is on the developer's
            laptop lid.
        alt:
          type: string
          minLength: 1
          maxLength: 300
          description: Alt text for the image. Also used to name the stored file, so write
            it the way someone would search for it.
          example: instagram mcp server posting from claude code
        branding:
          type: boolean
          description: Set to `false` to leave the logo and character out of this image
            (e.g. a clean diagram). Defaults to the project's image settings.
      required:
        - id
        - prompt
        - alt
    ArticleImagesResponse:
      type: object
      properties:
        article:
          $ref: "#/components/schemas/Article"
        images:
          $ref: "#/components/schemas/GenerateArticleImagesResult"
      required:
        - article
        - images
    GenerateArticleImagesResult:
      type: object
      properties:
        generated:
          type: array
          items:
            type: string
          description: Ids of the images that were generated and saved.
          example:
            - COVER
            - IMAGE_1
            - IMAGE_2
        failed:
          type: array
          items:
            type: string
          description: Ids of the images that are not in the article after this call. Send
            an inline id again only if its `{{ID}}` marker is still in the
            returned `article.content`; if the marker is gone, another call
            already placed an image there. Send the cover again if `coverImage`
            did not change. Every image that was generated is kept in the
            article's image gallery, placed or not.
          example:
            - IMAGE_3
      required:
        - generated
        - failed
    ImageSettingsResponse:
      type: object
      properties:
        imageSettings:
          $ref: "#/components/schemas/ImageSettings"
      required:
        - imageSettings
    ImageSettings:
      type: object
      properties:
        imageStyle:
          anyOf:
            - type: string
              enum:
                - ""
            - type: string
              minLength: 2
              maxLength: 2000
          description: A preset id from `stylePresets`, or your own style description.
            Prepended to every image prompt. An empty string selects the default
            preset.
          example: editorial-photo
        imageStyleDescription:
          type: string
          description: "The style text that is actually added to prompts: the preset's
            description, or `imageStyle` itself when it is custom."
        stylePresets:
          type: array
          items:
            $ref: "#/components/schemas/StylePreset"
        logoEnabled:
          type: boolean
          description: Whether the project's logo is placed in generated images, once per
            image.
        logoImageUrl:
          type:
            - string
            - "null"
          description: "The logo image attached to image prompts: the AI-specific logo
            variation when one is uploaded, otherwise the project logo."
        characterEnabled:
          type: boolean
          description: Whether the project's character appears in generated images as the
            main character.
        characterImageUrl:
          type:
            - string
            - "null"
          description: The character reference photo. Upload it from the dashboard's image
            settings.
        instructions:
          type: string
          description: Brand notes added to every image prompt, e.g. where the logo goes
            or what the character wears.
          example: The character always wears the black hoodie with the logo on the chest.
      required:
        - imageStyle
        - imageStyleDescription
        - stylePresets
        - logoEnabled
        - logoImageUrl
        - characterEnabled
        - characterImageUrl
        - instructions
    StylePreset:
      type: object
      properties:
        id:
          type: string
          example: editorial-photo
        label:
          type: string
          example: Editorial photo
        description:
          type: string
          example: Editorial photography style — clean, realistic, sharp focus, natural
            lighting, magazine-quality composition.
      required:
        - id
        - label
        - description
    UpdateImageSettingsBody:
      type: object
      properties:
        imageStyle:
          anyOf:
            - type: string
              enum:
                - ""
            - type: string
              minLength: 2
              maxLength: 2000
          description: A preset id from `stylePresets`, or your own style description.
            Prepended to every image prompt. An empty string selects the default
            preset.
          example: editorial-photo
        logoEnabled:
          type: boolean
        characterEnabled:
          type: boolean
          description: Requires a character photo on the project (`characterImageUrl`).
        instructions:
          type: string
          maxLength: 4000
          description: Brand notes added to every image prompt. Pass an empty string to
            clear them.
      additionalProperties: false
    ArticleEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - article.published
            - article.updated
            - article.unpublished
          description: Which event fired. `article.published` on an article becoming
            public, `article.updated` on a content change to an
            already-published article, `article.unpublished` when it returns to
            draft and leaves the public API.
          example: article.published
        timestamp:
          type: string
          description: When the event was generated, ISO 8601. Matches the
            `webhook-timestamp` header (seconds since the epoch) used to sign
            the request.
          example: 2026-06-01T09:00:00.000Z
        article:
          type: object
          properties:
            id:
              type: string
              example: clz9k2h1a0000abcd1234efgh
            slug:
              type: string
              example: best-crm-for-startups
            projectId:
              type: string
              example: proj_abc123
          required:
            - id
            - slug
            - projectId
          description: "Identifies the article that changed. Fetch `GET /articles/{slug}`
            for the current content: the event is a notification, not a
            snapshot."
      required:
        - type
        - timestamp
        - article
  parameters: {}
paths:
  /articles:
    get:
      operationId: listArticles
      tags:
        - Articles
      summary: List articles
      description: Returns a paginated list of articles for the project the API key is
        scoped to. The article body is included for each item.
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
          required: false
          name: page
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            example: 20
          required: false
          name: limit
          in: query
        - schema:
            type: boolean
            default: false
            example: false
            description: By default only `published` articles are returned. Set to `true` to
              also include `draft` articles (e.g. to preview work in progress).
          required: false
          description: By default only `published` articles are returned. Set to `true` to
            also include `draft` articles (e.g. to preview work in progress).
          name: includeDrafts
          in: query
      responses:
        "200":
          description: Articles retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListArticlesResponse"
              examples:
                withResults:
                  value:
                    articles:
                      - &a1
                        id: clx1abc234abcdef0123456789
                        slug: best-crm-for-startups
                        title: Best CRM for Startups in 2026
                        keyword: best crm for startups
                        metaDescription: A practical guide to choosing the right CRM when you're under
                          50 employees.
                        content: |-
                          # Introduction

                          If you're a startup founder evaluating CRM tools...
                        status: draft
                        datePublished: 2026-05-23T00:00:00.000Z
                        dateModified: null
                    pagination:
                      page: 1
                      limit: 20
                      total: 1
                      totalPages: 1
                      hasNext: false
                      hasPrev: false
                empty:
                  value:
                    articles: []
                    pagination:
                      page: 1
                      limit: 20
                      total: 0
                      totalPages: 0
                      hasNext: false
                      hasPrev: false
        "400":
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                missingAuth: &a2
                  value:
                    error:
                      title: Unauthorized
                      status: 401
                      code: missing_auth
                      message: Missing Authorization header
                      instance: /api/v1/articles
                invalidApiKey: &a3
                  value:
                    error:
                      title: Unauthorized
                      status: 401
                      code: invalid_api_key
                      message: Invalid API key
                      instance: /api/v1/articles
                apiKeyExpired:
                  value:
                    error:
                      title: Unauthorized
                      status: 401
                      code: api_key_expired
                      message: API key expired
                      instance: /api/v1/articles
        "403":
          description: API key lacks the required scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                insufficientScope:
                  value:
                    error:
                      title: Forbidden
                      status: 403
                      code: insufficient_scope
                      message: "Missing required scope: articles:read"
                      instance: /api/v1/articles
    post:
      operationId: createArticle
      tags:
        - Articles
      summary: Create an article
      description: Creates a new article in the project the API key is scoped to. Use
        this when you generate content with your own agents and want ArticlesQ
        to host it (e.g. for the backlinks exchange). The article body is
        markdown.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateArticleBody"
            examples:
              minimal:
                summary: Minimal — slug, title, keyword only
                value:
                  slug: best-crm-for-startups
                  title: Best CRM for Startups in 2026
                  keyword: best crm for startups
              full:
                summary: Full — with markdown body, meta description, and status
                value:
                  slug: best-crm-for-startups
                  title: Best CRM for Startups in 2026
                  keyword: best crm for startups
                  content: |-
                    # Introduction

                    If you're a startup founder evaluating CRM tools...
                  metaDescription: A practical guide to choosing the right CRM when you're under
                    50 employees.
                  status: draft
      responses:
        "201":
          description: Article created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleResponse"
              examples:
                created:
                  value:
                    article: *a1
        "400":
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                missingAuth: *a2
                invalidApiKey: *a3
        "403":
          description: API key lacks the required scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                insufficientScope:
                  value:
                    error:
                      title: Forbidden
                      status: 403
                      code: insufficient_scope
                      message: "Missing required scope: articles:write"
                      instance: /api/v1/articles
        "409":
          description: An article with the requested slug already exists in this project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                slugConflict:
                  value:
                    error:
                      title: Error
                      status: 409
                      code: slug_conflict
                      message: An article with that slug already exists in this project.
                      instance: /api/v1/articles
  /articles/{slug}:
    get:
      operationId: getArticle
      tags:
        - Articles
      summary: Get article by slug
      description: Returns a single article by slug, scoped to the project the API key
        authorises. Slugs are unique within a project.
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            example: best-crm-for-startups
          required: true
          name: slug
          in: path
        - schema:
            type: boolean
            example: false
            description: Whether to append the FAQ as a `## FAQ` markdown section to
              `content`. `true` forces inlining, `false` returns `content`
              without it. Omit to use the project's `inlineFaqInContent` default
              (on by default). The structured `faq` field is always returned
              either way.
          required: false
          description: Whether to append the FAQ as a `## FAQ` markdown section to
            `content`. `true` forces inlining, `false` returns `content` without
            it. Omit to use the project's `inlineFaqInContent` default (on by
            default). The structured `faq` field is always returned either way.
          name: inlineFaq
          in: query
        - schema:
            type: boolean
            default: false
            example: false
            description: By default a `draft` article returns 404 on this endpoint — only
              `published` articles are fetchable. Set to `true` to fetch a draft
              (e.g. to preview work in progress).
          required: false
          description: By default a `draft` article returns 404 on this endpoint — only
            `published` articles are fetchable. Set to `true` to fetch a draft
            (e.g. to preview work in progress).
          name: includeDrafts
          in: query
      responses:
        "200":
          description: Article retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleResponse"
              examples:
                found:
                  value:
                    article: *a1
        "401":
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                missingAuth: *a2
                invalidApiKey: *a3
        "403":
          description: API key lacks the required scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                insufficientScope:
                  value:
                    error:
                      title: Forbidden
                      status: 403
                      code: insufficient_scope
                      message: "Missing required scope: articles:read"
                      instance: /api/v1/articles/{slug}
        "404":
          description: Article not found in this project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                notFound:
                  value:
                    error:
                      title: Not Found
                      status: 404
                      code: not_found
                      message: Article not found
                      instance: /api/v1/articles/best-crm-for-startups
    patch:
      operationId: updateArticle
      tags:
        - Articles
      summary: Update an article
      description: Update editable fields on an article — currently `content` and
        `metaDescription`. Send only the fields you want to change. Returns the
        full updated article.
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            example: best-crm-for-startups
          required: true
          name: slug
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateArticleBody"
            examples:
              metaOnly:
                summary: Update only the meta description
                value:
                  metaDescription: Updated meta description with the latest pricing details.
              contentAndMeta:
                summary: Update both the body and the meta description
                value:
                  content: |-
                    # Introduction

                    New, better intro...
                  metaDescription: Practical CRM picks tested by real founders.
      responses:
        "200":
          description: Article updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleResponse"
              examples:
                updated:
                  value:
                    article:
                      id: clx1abc234abcdef0123456789
                      slug: best-crm-for-startups
                      title: Best CRM for Startups in 2026
                      keyword: best crm for startups
                      metaDescription: Updated meta description with the latest pricing details.
                      content: |-
                        # Introduction

                        If you're a startup founder evaluating CRM tools...
                      status: draft
                      datePublished: 2026-05-23T00:00:00.000Z
                      dateModified: null
        "400":
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                missingAuth: *a2
                invalidApiKey: *a3
        "403":
          description: API key lacks the required scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                insufficientScope:
                  value:
                    error:
                      title: Forbidden
                      status: 403
                      code: insufficient_scope
                      message: "Missing required scope: articles:write"
                      instance: /api/v1/articles/{slug}
        "404":
          description: Article not found in this project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                notFound:
                  value:
                    error:
                      title: Not Found
                      status: 404
                      code: not_found
                      message: Article not found
                      instance: /api/v1/articles/best-crm-for-startups
  /articles/{slug}/status:
    post:
      operationId: setArticleStatus
      tags:
        - Articles
      summary: Publish or unpublish an article
      description: Publishes a draft or returns a published article to draft. Needs
        the `articles:publish` scope, which is granted separately from
        `articles:write`, so a key can create and edit drafts without being able
        to publish them. Returns the updated article.
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            example: best-crm-for-startups
          required: true
          name: slug
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetArticleStatusBody"
      responses:
        "200":
          description: Status changed (or already the requested status)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleResponse"
        "400":
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                missingAuth: *a2
                invalidApiKey: *a3
        "403":
          description: API key lacks the required scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                insufficientScope:
                  value:
                    error:
                      title: Forbidden
                      status: 403
                      code: insufficient_scope
                      message: "Missing required scope: articles:publish"
                      instance: /api/v1/articles/{slug}/status
        "404":
          description: Article not found in this project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                notFound:
                  value:
                    error:
                      title: Not Found
                      status: 404
                      code: not_found
                      message: Article not found
                      instance: /api/v1/articles/best-crm-for-startups/status
  /articles/{slug}/images:
    post:
      operationId: generateArticleImages
      tags:
        - Articles
      summary: Generate article images
      description: Generates the cover and in-content images for an article from your
        prompts, stores them and puts them into the article. Write
        `{{IMAGE_1}}`, `{{IMAGE_2}}`, ... on their own lines in the content
        where each image belongs, then send one prompt per marker. Each prompt
        describes the scene; ArticlesQ adds the project's image style, its logo
        and character (following the project's image settings, see `GET
        /image-settings`) and the project's brand notes. Images are generated in
        parallel and the response returns the updated article. To replace an
        in-content image, put its marker back in the content with `PATCH
        /articles/{slug}` and send its prompt again.
      security:
        - ApiKeyAuth: []
      parameters:
        - schema:
            type: string
            example: best-crm-for-startups
          required: true
          name: slug
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateArticleImagesBody"
      responses:
        "200":
          description: Images generated and saved to the article
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleImagesResponse"
        "400":
          description: Invalid request body, or the content has no marker for an inline
            image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                missingAuth: *a2
                invalidApiKey: *a3
        "403":
          description: API key lacks the required scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                insufficientScope:
                  value:
                    error:
                      title: Forbidden
                      status: 403
                      code: insufficient_scope
                      message: "Missing required scope: images:write"
                      instance: /api/v1/articles/{slug}/images
        "404":
          description: Article not found in this project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                notFound:
                  value:
                    error:
                      title: Not Found
                      status: 404
                      code: not_found
                      message: Article not found
                      instance: /api/v1/articles/best-crm-for-startups/images
  /image-settings:
    get:
      operationId: getImageSettings
      tags:
        - Images
      summary: Get image settings
      description: "Returns the project's image settings: the style added to every
        image prompt, whether the logo and the character are used, their
        reference images, and the brand notes. Read them before writing image
        prompts so your scenes fit the style and the brand notes."
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: Image settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageSettingsResponse"
        "401":
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                missingAuth: *a2
                invalidApiKey: *a3
        "403":
          description: API key lacks the required scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                insufficientScope:
                  value:
                    error:
                      title: Forbidden
                      status: 403
                      code: insufficient_scope
                      message: "Missing required scope: images:read"
                      instance: /api/v1/image-settings
    patch:
      operationId: updateImageSettings
      tags:
        - Images
      summary: Update image settings
      description: Update the project's image style, turn the logo or the character on
        or off, or edit the brand notes. Send only the fields you want to
        change. Returns the full image settings.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateImageSettingsBody"
      responses:
        "200":
          description: Image settings updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageSettingsResponse"
        "400":
          description: Invalid request body, or the character was enabled without a
            character photo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                missingAuth: *a2
                invalidApiKey: *a3
        "403":
          description: API key lacks the required scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                insufficientScope:
                  value:
                    error:
                      title: Forbidden
                      status: 403
                      code: insufficient_scope
                      message: "Missing required scope: images:write"
                      instance: /api/v1/image-settings
webhooks:
  article.published:
    post:
      tags: &a4
        - Webhooks
      security: &a5 []
      operationId: article-published
      summary: Article published
      description: "Sent when an article becomes public. Every delivery is signed:
        verify the `webhook-id`, `webhook-timestamp` and `webhook-signature`
        headers with the endpoint's signing secret before acting on the body.
        See Setup webhooks for a copy-paste handler."
      requestBody:
        description: Event payload
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArticleEvent"
            example:
              type: article.published
              timestamp: 2026-06-01T09:00:00.000Z
              article:
                id: clz9k2h1a0000abcd1234efgh
                slug: best-crm-for-startups
                projectId: proj_abc123
      responses:
        "200":
          description: Any 2xx marks the delivery as accepted. Answer immediately and do
            the work afterwards; the request times out after 5 seconds.
  article.updated:
    post:
      tags: *a4
      security: *a5
      operationId: article-updated
      summary: Article updated
      description: "Sent when the content of an already-published article changes.
        Every delivery is signed: verify the `webhook-id`, `webhook-timestamp`
        and `webhook-signature` headers with the endpoint's signing secret
        before acting on the body. See Setup webhooks for a copy-paste handler."
      requestBody:
        description: Event payload
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArticleEvent"
            example:
              type: article.updated
              timestamp: 2026-06-01T09:00:00.000Z
              article:
                id: clz9k2h1a0000abcd1234efgh
                slug: best-crm-for-startups
                projectId: proj_abc123
      responses:
        "200":
          description: Any 2xx marks the delivery as accepted. Answer immediately and do
            the work afterwards; the request times out after 5 seconds.
  article.unpublished:
    post:
      tags: *a4
      security: *a5
      operationId: article-unpublished
      summary: Article unpublished
      description: "Sent when an article returns to draft and leaves the public API.
        Every delivery is signed: verify the `webhook-id`, `webhook-timestamp`
        and `webhook-signature` headers with the endpoint's signing secret
        before acting on the body. See Setup webhooks for a copy-paste handler."
      requestBody:
        description: Event payload
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArticleEvent"
            example:
              type: article.unpublished
              timestamp: 2026-06-01T09:00:00.000Z
              article:
                id: clz9k2h1a0000abcd1234efgh
                slug: best-crm-for-startups
                projectId: proj_abc123
      responses:
        "200":
          description: Any 2xx marks the delivery as accepted. Answer immediately and do
            the work afterwards; the request times out after 5 seconds.
