Napkin.AI Visuals API

openapi: 3.2.0
info:
  title: Napkin AI Visuals API
  version: 1.1.16
  description: 'Developer-preview API for programmatic visual generation with Napkin AI. Submit text and Napkin generates editable visuals (diagrams, charts, icons, infographics) returned as downloadable PNG, SVG, or PPT files. Requests are processed asynchronously: create a visual request, poll its status, then download each generated file. Both status and file URLs expire 30 minutes after generation. This spec is a faithful, partial capture of the published developer-preview documentation at https://api.napkin.ai/ (endpoints, auth, and response codes are documented verbatim; request-body fields are the subset the docs and changelog document explicitly). Endpoints may change. Report issues to api@napkin.ai.'
  contact:
    name: Napkin AI API
    email: api@napkin.ai
    url: https://api.napkin.ai/
  termsOfService: https://www.napkin.ai/terms-conditions/
  x-apievangelist-note: Generated by the API Evangelist enrichment pipeline from the published developer-preview documentation (no provider-published OpenAPI was found at /openapi.json). method=generated, source=https://api.napkin.ai/
servers:
- url: https://api.napkin.ai/v1
  description: Production (developer preview)
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Visuals
  description: Programmatic visual content generation.
paths:
  /visual:
    post:
      operationId: createVisualRequest
      tags:
      - Visuals
      summary: Create visual request
      description: Create a new visual content generation request. The request is processed asynchronously; use the returned request id to poll status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VisualRequest'
      responses:
        '201':
          description: Visual request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisualRequestCreated'
        '400':
          description: Invalid request data
        '401':
          description: Authentication required or invalid token
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /visual/{request-id}/status:
    get:
      operationId: getVisualRequestStatus
      tags:
      - Visuals
      summary: Get visual request status
      description: Retrieve the current status and details of a visual request. Status is one of pending, completed, or failed. When completed, the response includes a generated_files array with download links and metadata. Status and file URLs expire 30 minutes after generation.
      parameters:
      - name: request-id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Request status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisualRequestStatus'
        '400':
          description: Invalid request ID format
        '401':
          description: Authentication required or invalid token
        '403':
          description: Access denied - request belongs to another user
        '404':
          description: Request not found
        '410':
          description: Request has expired and is no longer available
        '500':
          description: Internal server error
  /visual/{request-id}/file/{file-id}:
    get:
      operationId: downloadVisualFile
      tags:
      - Visuals
      summary: Download generated file
      description: Download a specific file generated by a completed visual request. The complete download URL is provided in the generated_files array from the status endpoint. Authentication headers are required. Files are only available for requests with status completed and expire 30 minutes after generation.
      parameters:
      - name: request-id
        in: path
        required: true
        schema:
          type: string
      - name: file-id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: File downloaded successfully
          content:
            image/svg+xml: {}
            image/png: {}
            application/pdf: {}
            application/vnd.openxmlformats-officedocument.presentationml.presentation: {}
        '400':
          description: Invalid request ID or file ID format
        '401':
          description: Authentication required or invalid token
        '403':
          description: Access denied - request belongs to another user
        '404':
          description: Request or file not found
        '410':
          description: Request has expired and is no longer available
        '500':
          description: Internal server error
components:
  schemas:
    GeneratedFile:
      type: object
      properties:
        file_id:
          type: string
        url:
          type: string
          description: Authenticated download URL (expires 30 minutes after generation).
        content_type:
          type: string
          example: image/svg+xml
    VisualRequest:
      type: object
      description: Visual generation request. Fields below are the subset documented in the developer-preview docs and changelog; the live API may accept more.
      required:
      - content
      properties:
        content:
          type: string
          description: The text content Napkin turns into visuals.
        language:
          type: string
          description: Optional but strongly recommended language hint. If omitted the system auto-detects the language.
        style_id:
          type: string
          description: Visual style to render with (see the Styles reference).
        sort_strategy:
          type: string
          description: Ordering strategy for returned visuals. Includes a "variation" strategy that increases variety in visual layout results.
        number_of_visuals:
          type: integer
          description: Number of visuals to request.
    VisualError:
      type: object
      description: Present on failed requests; when present, generated_files is empty.
      properties:
        code:
          type: string
          enum:
          - no_credits
          - no_visuals
        message:
          type: string
    VisualRequestCreated:
      type: object
      properties:
        request_id:
          type: string
          description: Identifier used to poll status and download files.
        status:
          type: string
          enum:
          - pending
          - completed
          - failed
    VisualRequestStatus:
      type: object
      properties:
        status:
          type: string
          enum:
          - pending
          - completed
          - failed
        generated_files:
          type: array
          description: Present when status is completed; download links expire after 30 minutes.
          items:
            $ref: '#/components/schemas/GeneratedFile'
        error:
          $ref: '#/components/schemas/VisualError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication required for all endpoints. Use a Napkin AI account API token in the Authorization header.
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization code flow (beta). Your application must be approved by the Napkin AI team to obtain client credentials.
      flows:
        authorizationCode:
          authorizationUrl: https://api.napkin.ai/v1/oauth/authorize
          tokenUrl: https://api.napkin.ai/v1/oauth/token
          refreshUrl: https://api.napkin.ai/v1/oauth/token
          scopes:
            user: Access to basic user profile information (email, name, user ID)
            generation: Ability to create visual generations on behalf of the user