genko.me Schema API

openapi: 3.2.0
info:
  title: genko.me Delivery Schema API
  version: 1.0.0
  description: A read-only delivery API that authenticates with an API key and returns content managed in genko.me as JSON.
  termsOfService: https://docs.genko.me/legal/terms
  contact:
    url: https://genko.me/contact
servers:
- url: https://api.genko.me/v1
security:
- ApiKeyHeader: []
tags:
- name: Schema
  description: Retrieve API definitions (for CLI type generation)
paths:
  /{workspace}/_schema:
    get:
      operationId: getWorkspaceSchema
      tags:
      - Schema
      summary: Retrieve the API definitions within a workspace
      description: Returns the name, endpoint, kind, and field definitions of the APIs accessible with the API key. If the API key is scoped to specific APIs, only those are included. Content bodies are not returned.
      parameters:
      - $ref: '#/components/parameters/Workspace'
      responses:
        '200':
          description: List of API definitions
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/WorkspaceNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Forbidden:
      description: The workspace that issued the API key does not match the workspace in the URL.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: This API key cannot be used for the specified workspace.
    TooManyRequests:
      description: The per-API-key rate limit (300 requests per minute) was exceeded. No rate-limit-related response headers are included.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Too many requests. Please try again later.
    Unauthorized:
      description: The X-API-KEY header is missing, the key is invalid, revoked, or outside its validity period, or it lacks read permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: An API key is required.
    InternalServerError:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Internal Server Error
    WorkspaceNotFound:
      description: The workspace was not found. This is checked before API key validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Workspace not found.
  schemas:
    ApiDefinition:
      type: object
      required:
      - name
      - endpoint
      - kind
      - fields
      properties:
        name:
          type: string
          description: The API's display name
        endpoint:
          type: string
          description: The API's endpoint name
        kind:
          type: string
          enum:
          - list
          - object
          description: list is list kind, object is object kind
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FieldDefinition'
    SchemaResponse:
      type: object
      required:
      - workspace
      - apis
      properties:
        workspace:
          type: string
          description: The workspace slug
        apis:
          type: array
          items:
            $ref: '#/components/schemas/ApiDefinition'
    Error:
      type: object
      description: Error response. Branch on the HTTP status; use message to check the cause.
      required:
      - message
      properties:
        message:
          type: string
          description: A human-readable error message, in English.
    FieldDefinition:
      type: object
      description: The field definition. Returned as-is from what was saved in the admin UI, so keys not documented here may be included.
      required:
      - id
      - name
      - type
      - required
      properties:
        id:
          type: string
          description: The field ID (the key in the delivery response)
        name:
          type: string
          description: The field's display name
        type:
          type: string
          enum:
          - text
          - textarea
          - richtext
          - image
          - images
          - datetime
          - boolean
          - select
          - reference
          - references
          - number
          - file
          - extension
        required:
          type: boolean
        settings:
          type: object
          description: Settings specific to each field type
          properties:
            multiple:
              type: boolean
              description: Whether select allows multiple selections
            options:
              type: array
              items:
                type: string
              description: The options for select
            referenceApi:
              type: string
              description: The endpoint of the API referenced by reference/references
          additionalProperties: true
      additionalProperties: true
  parameters:
    Workspace:
      name: workspace
      in: path
      required: true
      description: The workspace slug (workspace ID).
      schema:
        type: string
  headers:
    CacheControl:
      description: Responses to successfully authenticated requests always carry `private, no-store`.
      schema:
        type: string
        const: private, no-store
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: The API key issued for the target workspace (a string starting with gk_). Each key is rate-limited to 300 requests per minute.
externalDocs:
  url: https://docs.genko.me/api-reference/delivery