Storyblok Collaborators API

openapi: 3.2.0
info:
  title: Storyblok Management Collaborators 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: Collaborators
  description: Collaborators are users invited to a Storyblok space with specific roles and permissions. The Management API allows adding, updating, and removing collaborators.
paths:
  /spaces/{space_id}/collaborators:
    get:
      operationId: listCollaborators
      summary: List collaborators in a space
      description: Returns a list of all collaborators who have access to the space, including their roles, permissions, and invitation status.
      tags:
      - Collaborators
      parameters:
      - $ref: '#/components/parameters/SpaceId'
      responses:
        '200':
          description: A list of collaborators was returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  collaborators:
                    type: array
                    items:
                      $ref: '#/components/schemas/Collaborator'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: addCollaborator
      summary: Add a collaborator
      description: Invites a user to the space by email address and assigns them a role. If the user already has a Storyblok account they will be added immediately; otherwise an invitation email is sent.
      tags:
      - Collaborators
      parameters:
      - $ref: '#/components/parameters/SpaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - collaborator
              properties:
                collaborator:
                  $ref: '#/components/schemas/CollaboratorInput'
      responses:
        '201':
          description: The collaborator was added successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  collaborator:
                    $ref: '#/components/schemas/Collaborator'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /spaces/{space_id}/collaborators/{collaborator_id}:
    delete:
      operationId: deleteCollaborator
      summary: Remove a collaborator
      description: Removes a collaborator from the space, revoking their access. The user's Storyblok account is not deleted; they simply lose access to this space.
      tags:
      - Collaborators
      parameters:
      - $ref: '#/components/parameters/SpaceId'
      - name: collaborator_id
        in: path
        description: Numeric ID of the collaborator to remove.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The collaborator was removed successfully.
        '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'
    UnprocessableEntity:
      description: The request body contained validation errors. Check the error message for details on which fields failed validation.
      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:
    Collaborator:
      type: object
      description: A collaborator with access to the space, including their role assignment and invitation status.
      properties:
        id:
          type: integer
          description: Unique numeric identifier of the collaborator record.
        user_id:
          type: integer
          description: Numeric ID of the associated Storyblok user account.
        role:
          type: string
          description: Role assigned to the collaborator. Built-in roles are admin, editor, and viewer.
          enum:
          - admin
          - editor
          - viewer
        invited:
          type: boolean
          description: True if an invitation email was sent and not yet accepted.
        space_role_id:
          type: integer
          nullable: true
          description: ID of a custom space role if a custom role is assigned.
        space_role_ids:
          type: array
          description: List of custom space role IDs assigned to this collaborator.
          items:
            type: integer
        user:
          type: object
          description: Basic user profile information.
          properties:
            userid:
              type: string
              description: Storyblok username.
            email:
              type: string
              format: email
              description: Email address of the collaborator.
            avatar:
              type: string
              nullable: true
              description: URL of the user's avatar image.
            friendly_name:
              type: string
              description: Display name of the user.
    Error:
      type: object
      description: Error response returned when an API request fails.
      properties:
        error:
          type: string
          description: Human-readable message describing the error.
    CollaboratorInput:
      type: object
      description: Input for inviting a collaborator to a space.
      required:
      - email
      - role
      properties:
        email:
          type: string
          format: email
          description: Email address of the user to invite.
        role:
          type: string
          description: Role to assign to the collaborator.
          enum:
          - admin
          - editor
          - viewer
        space_role_id:
          type: integer
          description: ID of a custom space role to assign instead of a built-in role.
  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