Storyblok Spaces API

openapi: 3.2.0
info:
  title: Storyblok Management Spaces API
  description: The Storyblok Management API is a REST API that allows developers to programmatically create, read, update, and delete content and configuration within a Storyblok space. It supports managing stories, components, assets, datasources, collaborators, webhooks, and space settings. The API uses OAuth or personal access tokens for authentication and is suitable for building editorial tooling, content migration scripts, CI/CD pipelines, and automated publishing workflows. All write operations are scoped to individual spaces and respect role-based access control.
  version: '1'
  contact:
    name: Storyblok Support
    url: https://www.storyblok.com/contact
  termsOfService: https://www.storyblok.com/legal/terms-of-service
servers:
- url: https://mapi.storyblok.com/v1
  description: Management API Production Server
security:
- personalAccessToken: []
- oauthToken: []
tags:
- name: Spaces
  description: Spaces are the top-level containers in Storyblok. Each space has its own content, components, assets, and settings. The spaces endpoint allows retrieval and management of space metadata and configuration.
paths:
  /spaces/{space_id}:
    get:
      operationId: getSpace
      summary: Retrieve a space
      description: Returns the details of a Storyblok space including its name, plan, regional endpoint, domain configuration, language settings, and statistics. This endpoint is useful for validating space access and retrieving configuration needed for other API calls.
      tags:
      - Spaces
      parameters:
      - $ref: '#/components/parameters/SpaceId'
      responses:
        '200':
          description: The space details were returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  space:
                    $ref: '#/components/schemas/Space'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    SpaceId:
      name: space_id
      in: path
      description: Numeric ID of the Storyblok space.
      required: true
      schema:
        type: integer
      example: 12345
  responses:
    Unauthorized:
      description: Authentication failed. Verify the Authorization header contains a valid personal access token or OAuth token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Space:
      type: object
      description: A Storyblok space containing all content, components, assets, and settings for a project.
      properties:
        id:
          type: integer
          description: Unique numeric identifier of the space.
        name:
          type: string
          description: Display name of the space.
        domain:
          type: string
          description: Primary domain associated with the space for preview links.
        version:
          type: integer
          description: Current cache version of the space content.
        languages:
          type: array
          description: List of language codes supported by this space.
          items:
            type: string
        default_lang:
          type: string
          description: Default language code for the space.
        plan:
          type: string
          description: Current subscription plan name for the space.
        plan_level:
          type: integer
          description: Numeric plan level indicating feature availability.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the space was created.
        stories_count:
          type: integer
          description: Total number of stories in the space.
        assets_count:
          type: integer
          description: Total number of assets in the space.
        collaborators_count:
          type: integer
          description: Total number of collaborators with access to the space.
    Error:
      type: object
      description: Error response returned when an API request fails.
      properties:
        error:
          type: string
          description: Human-readable message describing the error.
  securitySchemes:
    personalAccessToken:
      type: http
      scheme: bearer
      description: Personal access token generated in the Storyblok account settings. Provides access to all spaces the account has permissions for.
    oauthToken:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token for third-party application integrations. Scoped to specific spaces and permissions granted during authorization.
externalDocs:
  description: Storyblok Management API Documentation
  url: https://www.storyblok.com/docs/api/management