imejis-io Designs API

openapi: 3.2.0
info:
  title: Imejis Designs API
  version: 1.0.0
  summary: The REST API for Imejis image generation.
  description: 'The endpoints an agent or integration calls directly. Render a design to a finished image (the image API), read and list designs, fetch a design''s render config, check usage, and manage render keys. One endpoint renders: pass a design id, get an image back. Design authoring (the v2 component document) runs over MCP, so connect the MCP server at https://api.imejis.io/api/mcp and call get_design_guide for the full component schema.'
  contact:
    name: Imejis
    email: support@imejis.io
    url: https://www.imejis.io/apis
servers:
- url: https://api.imejis.io
  description: Imejis API
- url: https://render.imejis.io/v1
  description: Imejis render service
security:
- bearerAuth: []
tags:
- name: Designs
  description: Read and list designs.
paths:
  /designs/v2:
    get:
      tags:
      - Designs
      operationId: listDesigns
      summary: List designs
      description: List the authenticated user's designs, most recently updated first. Paginate with `$page` and `$limit`.
      parameters:
      - name: $page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: $limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      responses:
        '200':
          description: A page of designs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDesigns'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /designs/v2/{id}:
    get:
      tags:
      - Designs
      operationId: getDesign
      summary: Get a design document
      description: The full v2 design document, the same shape the MCP `get_design` tool returns.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The design document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Design'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /designs/v2/{id}/config:
    get:
      tags:
      - Designs
      operationId: getDesignRenderConfig
      summary: Get a design's render endpoint and dynamic fields
      description: Returns the render endpoint for the design plus its overridable dynamic fields (`data.pure` nested, `data.flatten` dot-path keys).
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The render config.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    RenderConfig:
      type: object
      additionalProperties: true
      properties:
        render:
          type: string
          format: uri
          description: The render endpoint for this design.
        data:
          type: object
          additionalProperties: true
          properties:
            pure:
              type: object
              additionalProperties: true
            flatten:
              type: object
              additionalProperties: true
        variations:
          type: array
          description: The sizes this design offers (the base/master plus each variation). Use a size's `id` as the `?variation=` value on the render URL; omit it (or use "master") for the base size.
          items:
            type: object
            additionalProperties: true
            properties:
              id:
                type: string
              name:
                type: string
              dimensions:
                type: object
                properties:
                  width:
                    type: number
                  height:
                    type: number
    PaginatedDesigns:
      type: object
      additionalProperties: true
      properties:
        docs:
          type: array
          items:
            $ref: '#/components/schemas/DesignSummary'
        page:
          type: integer
        totalPages:
          type: integer
        hasNextPage:
          type: boolean
    DesignSummary:
      type: object
      additionalProperties: true
      properties:
        _id:
          type: string
        name:
          type: string
        updatedAt:
          type: string
          format: date-time
    Design:
      type: object
      additionalProperties: true
      description: A v2 design document. See MCP get_design_guide for the full component schema.
      properties:
        _id:
          type: string
        name:
          type: string
        design:
          type: object
          additionalProperties: true
  responses:
    NotFound:
      description: No such resource.
    Unauthorized:
      description: Missing or invalid credentials.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer access token issued by Imejis. See https://api.imejis.io/auth.md and /.well-known/oauth-protected-resource.
    renderKeyHeader:
      type: apiKey
      in: header
      name: dma-api-key
      description: A render API key. Manage keys under /settings/api-keys.
    renderKeyQuery:
      type: apiKey
      in: query
      name: dma-api-key
      description: A render API key passed as a query param (GET only).
externalDocs:
  url: https://www.imejis.io/apis
  description: Imejis API and agent docs