genko.me Contents API

openapi: 3.2.0
info:
  title: genko.me Delivery Contents 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: Contents
  description: Retrieve content
paths:
  /{workspace}/{endpoint}:
    get:
      operationId: getContents
      tags:
      - Contents
      summary: Retrieve a list-kind listing or a single object-kind entry
      description: 'The response shape depends on the API''s kind. For list kind (kind: list), it returns a paginated list of published content (ContentList). For object kind (kind: object), it returns a single content entry (ContentEntry) directly. limit, offset, orders, filters, and q are only used for list kind; draftKey is only used for object kind. Any other combination is ignored.'
      parameters:
      - $ref: '#/components/parameters/Workspace'
      - $ref: '#/components/parameters/Endpoint'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Orders'
      - $ref: '#/components/parameters/Filters'
      - $ref: '#/components/parameters/Q'
      - $ref: '#/components/parameters/Depth'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/DraftKey'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/LangFallback'
      - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: ContentList for list kind, ContentEntry for object kind. Which one is returned is determined by the API's kind (the kind field from _schema).
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ContentList'
                - $ref: '#/components/schemas/ContentEntry'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The workspace or API was not found (including APIs outside the API key's scope), or there is no retrievable content for an object-kind API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: API not found.
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /{workspace}/_views/{endpoint}:
    get:
      operationId: getContentViews
      tags:
      - Contents
      summary: Retrieve view counts for list-kind entries
      description: Returns the all-time view count and the count over the last `days` JST days (including today) for each requested entry ID. IDs that are not entries of this API, or have no recorded views, return zeros.
      parameters:
      - $ref: '#/components/parameters/Workspace'
      - $ref: '#/components/parameters/Endpoint'
      - name: ids
        in: query
        required: true
        description: Comma-separated entry IDs (the id field in the delivery response). 1 to 100 IDs, each matching [A-Za-z0-9_-]{1,64}.
        schema:
          type: string
      - name: days
        in: query
        required: false
        description: The window for `recent`, in JST days including today. An integer from 1 to 365. Defaults to 30.
        schema:
          type: integer
          minimum: 1
          maximum: 365
          default: 30
      responses:
        '200':
          description: View counts keyed by entry ID
          content:
            application/json:
              schema:
                type: object
                required:
                - days
                - views
                properties:
                  days:
                    type: integer
                  views:
                    type: object
                    additionalProperties:
                      type: object
                      required:
                      - total
                      - recent
                      properties:
                        total:
                          type: integer
                        recent:
                          type: integer
              example:
                days: 30
                views:
                  AAAAAAAAAAAA:
                    total: 120
                    recent: 18
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The workspace was not found, or the API does not exist, is not list kind, or is outside the API key's scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: API not found.
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /{workspace}/{endpoint}/{contentId}:
    get:
      operationId: getContent
      tags:
      - Contents
      summary: Retrieve a single entry from list-kind content
      description: Only usable with list-kind APIs. Returns 404 for object-kind APIs. The response is not wrapped in contents; a single object is returned directly.
      parameters:
      - $ref: '#/components/parameters/Workspace'
      - $ref: '#/components/parameters/Endpoint'
      - name: contentId
        in: path
        required: true
        description: The content ID (the id field in the delivery response). A 12-character alphanumeric immutable ID, not a title or slug.
        schema:
          type: string
      - $ref: '#/components/parameters/Depth'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/DraftKey'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/LangFallback'
      - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: A single content entry
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentEntry'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The workspace was not found; the API does not exist, is not list kind, or is outside the API key's scope; the content does not exist or does not satisfy publication conditions; or draftKey does not match.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Content not found.
        '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.
    InternalServerError:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Internal Server Error
    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.
    BadRequest:
      description: The query format or value is invalid (limit, offset, orders, filters, q, depth, fields, draftKey, or lang), or lang names a language that is not configured for the workspace or a sub language on an API without multilingual enabled.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: limit must be an integer between 1 and 100.
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: List kind only. The number of entries to retrieve per request. An empty string, an out-of-range value, or a non-integer value results in 400.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    LangFallback:
      name: lang_fallback
      in: query
      required: false
      description: Only meaningful with a sub-language lang. When true, entries without a published version in that language are returned in their published main-language version instead (applies to listing, totalCount, single retrieval, and object kind). With lang, a value other than true or false results in 400; without lang the parameter is ignored. Not applied to draftKey previews.
      schema:
        type: boolean
        default: false
    Fields:
      name: fields
      in: query
      required: false
      description: Comma-separated field IDs to return (up to 50 items). id is always included; createdAt, updatedAt, and publishedAt are returned only if specified. Nonexistent IDs are ignored. Fields within expanded referenced entries are not filtered. An empty string is treated as all fields.
      schema:
        type: string
      example: title,publishedAt
    DraftKey:
      name: draftKey
      in: query
      required: false
      description: The draft preview key (1-64 characters). Only used for single-entry retrieval and object kind; ignored for list responses. Returns 400 if the format is invalid, or 404 if it does not match. Even during preview, only published content is expanded for referenced entries.
      schema:
        type: string
        minLength: 1
        maxLength: 64
    Q:
      name: q
      in: query
      required: false
      description: List kind only. Performs a case-insensitive partial match search across text, textarea, and richtext fields. An empty string is treated as not specified.
      schema:
        type: string
        maxLength: 100
    Workspace:
      name: workspace
      in: path
      required: true
      description: The workspace slug (workspace ID).
      schema:
        type: string
    Offset:
      name: offset
      in: query
      required: false
      description: List kind only. The starting offset, counted from entry 0. An empty string, a negative number, or a non-integer value results in 400.
      schema:
        type: integer
        minimum: 0
        default: 0
    Include:
      name: include
      in: query
      required: false
      description: Comma-separated extra keys to add to each returned entry. Currently only _langs is supported (see ContentEntry._langs). With lang, an unknown key results in 400; without lang, unknown keys are ignored. Without include, the response shape is unchanged.
      schema:
        type: string
      example: _langs
    Endpoint:
      name: endpoint
      in: path
      required: true
      description: The API's endpoint name.
      schema:
        type: string
    Filters:
      name: filters
      in: query
      required: false
      description: List kind only. Chain `fieldId[operator]value` conditions with [and] or [or] (mixing both, or parentheses, is not allowed; up to 10 conditions, 1,000 characters total). Operators are equals, not_equals, contains, not_contains, greater_than, less_than, exists, not_exists. The usable operators depend on the field type (e.g. the meta id field allows equals and not_equals; createdAt, updatedAt, and publishedAt allow greater_than and less_than). An unknown field, an operator not supported by that field, or a malformed value results in 400.
      schema:
        type: string
        maxLength: 1000
      example: category[equals]tech[and]featured[equals]true
    Orders:
      name: orders
      in: query
      required: false
      description: List kind only. Specify up to 3 sort keys, comma-separated, in priority order. Prefix a key with - for descending order. Usable keys are createdAt, updatedAt, publishedAt, views (the all-time page view count, 0 when none), or the field ID of a number, datetime, text, or boolean field. NULLs sort last. An empty string is treated as the default.
      schema:
        type: string
        default: -publishedAt
      example: -publishedAt
    Lang:
      name: lang
      in: query
      required: false
      description: The language to return, as a language code configured for the workspace (e.g. en, zh-CN; case is normalized). Omitting it, or passing the workspace's main language, returns the main-language content exactly as without the parameter. A sub language is only accepted on APIs with multilingual enabled; publication, filters, q, orders, and the createdAt/updatedAt/publishedAt values are all evaluated on that language's version. Each language is published independently. Reference fields pointing to multilingual APIs are expanded in the same language (and fallback); references to other APIs use the main language. With draftKey, the key of that language's version is checked. An unconfigured language, or a sub language on an API without multilingual enabled, results in 400.
      schema:
        type: string
        maxLength: 35
      example: en
    Depth:
      name: depth
      in: query
      required: false
      description: The expansion depth for reference fields. 0 leaves the referenced ID as-is, 1 expands one level, and 2 expands one further level into the referenced entry's own references. An empty string or an out-of-range value results in 400.
      schema:
        type: integer
        enum:
        - 0
        - 1
        - 2
        default: 1
  schemas:
    ContentEntry:
      type: object
      description: A single content entry. User-defined fields appear directly at the top level, keyed by field ID (the value's shape depends on the field type and depth; see https://docs.genko.me/api-reference/values). If fields is specified, only id and the specified keys are included.
      required:
      - id
      properties:
        id:
          type: string
          description: The immutable public content ID (12-character alphanumeric).
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Update timestamp
        publishedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Publication timestamp. May be null, such as during a draft preview.
        _langs:
          type: object
          description: Only present with include=_langs. Not added to expanded referenced entries.
          required:
          - current
          - available
          properties:
            current:
              type: string
              description: The language actually returned (the main language when lang_fallback fell back).
            available:
              type: array
              items:
                type: string
              description: Languages with a published version of this entry, main language first. Sub languages are listed only for multilingual APIs.
      additionalProperties: true
    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.
    ContentList:
      type: object
      description: The listing response for a list-kind API. Returns 200 even when there are no matches, with contents as an empty array.
      required:
      - contents
      - totalCount
      - offset
      - limit
      properties:
        contents:
          type: array
          items:
            $ref: '#/components/schemas/ContentEntry'
        totalCount:
          type: integer
          minimum: 0
          description: The total count of entries satisfying the publication conditions and filters/q.
        offset:
          type: integer
          minimum: 0
          description: The starting offset
        limit:
          type: integer
          minimum: 1
          maximum: 100
          description: The maximum number of entries returned
  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