openapi: 3.0.2
info:
  title: Zeplin Authorization Colors API
  description: Access your resources in Zeplin
  version: 1.38.0
  contact:
    name: Zeplin
    url: https://zeplin.io
    email: support@zeplin.io
servers:
- url: https://api.zeplin.dev
security:
- PersonalAccessToken: []
- OAuth2: []
tags:
- name: Colors
paths:
  /v1/projects/{project_id}/colors:
    get:
      tags:
      - Colors
      summary: Get project colors
      description: 'This endpoint returns all of the colors in a project.


        You need to be a member of the project or a member of the organization that owns the project. Returns `Not Found` response otherwise.

        '
      operationId: GetProjectColors
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/include_linked_styleguides'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Color'
              examples:
                Project Colors:
                  value:
                  - $ref: '#/components/examples/color/value'
        '404':
          $ref: '#/components/responses/projectNotFound'
        '422':
          $ref: '#/components/responses/projectArchived'
    post:
      tags:
      - Colors
      summary: Create project color
      description: Create a color in the project's local styleguide
      operationId: CreateProjectColor
      parameters:
      - $ref: '#/components/parameters/project_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ColorCreateBody'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityReference'
              examples:
                response:
                  $ref: '#/components/examples/entityReference'
        '403':
          $ref: '#/components/responses/cannotCreateAColor'
        '404':
          $ref: '#/components/responses/projectNotFound'
        '422':
          $ref: '#/components/responses/notAProjectMemberOrArchived'
  /v1/projects/{project_id}/colors{color_id}:
    patch:
      tags:
      - Colors
      summary: Update project color
      description: Update a color in the project's local styleguide
      operationId: UpdateProjectColor
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/color_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ColorUpdateBody'
      responses:
        '204':
          $ref: '#/components/responses/noContent'
        '403':
          $ref: '#/components/responses/cannotUpdateAProjectColor'
        '404':
          $ref: '#/components/responses/projectOrColorNotFound'
        '422':
          $ref: '#/components/responses/notAProjectMemberOrArchived'
  /v1/styleguides/{styleguide_id}/colors:
    get:
      tags:
      - Colors
      summary: Get styleguide colors
      description: 'Returns colors in a styleguide that user has access.


        See [Styleguide docs](#getstyleguide) for more details about how `linked_project` and `linked_styleguide` parameters can be used to retrieve resources from styleguides that user is eligible to access.

        '
      operationId: GetStyleguideColors
      parameters:
      - $ref: '#/components/parameters/styleguide_id'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/linked_project'
      - $ref: '#/components/parameters/linked_styleguide'
      - $ref: '#/components/parameters/include_linked_styleguides'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Color'
              examples:
                Styleguide Colors:
                  value:
                  - $ref: '#/components/examples/color/value'
        '404':
          $ref: '#/components/responses/styleguideNotFound'
        '422':
          $ref: '#/components/responses/styleguideArchived'
    post:
      tags:
      - Colors
      summary: Create styleguide color
      description: Create a color in the styleguide's local styleguide
      operationId: CreateStyleguideColor
      parameters:
      - $ref: '#/components/parameters/styleguide_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ColorCreateBody'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityReference'
              examples:
                response:
                  $ref: '#/components/examples/entityReference'
        '403':
          $ref: '#/components/responses/cannotCreateAStyleguideColor'
        '404':
          $ref: '#/components/responses/styleguideNotFound'
        '422':
          $ref: '#/components/responses/notAStyleguideMemberOrArchived'
  /v1/styleguides/{styleguide_id}/colors/{color_id}:
    patch:
      tags:
      - Colors
      summary: Update styleguide color
      description: Update a color in the styleguide
      operationId: UpdateStyleguideColor
      parameters:
      - $ref: '#/components/parameters/styleguide_id'
      - $ref: '#/components/parameters/color_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ColorUpdateBody'
      responses:
        '204':
          $ref: '#/components/responses/noContent'
        '403':
          $ref: '#/components/responses/cannotUpdateAStyleguideColor'
        '404':
          $ref: '#/components/responses/styleguideOrColorNotFound'
        '422':
          $ref: '#/components/responses/notAStyleguideMemberOrArchived'
components:
  examples:
    resourceSourceForStyleguide:
      summary: Source for Styleguide
      value:
        styleguide:
          $ref: '#/components/examples/resourceStyleguideSource/value'
    resourceStyleguideSource:
      summary: Source Styleguide
      value:
        id: 5db981be9df2b3e1bfa19ef2
        name: Discovery 1
        platform: web
        parent:
          id: 5db981be9df2b3e1bfa19ef2
    resourceSourceForProject:
      summary: Source for Project
      value:
        project:
          $ref: '#/components/examples/resourceProjectSource/value'
    resourceProjectSource:
      summary: Source Project
      value:
        id: 5db81e73e1e36ee19f138c1a
        name: HAL 9000
        platform: web
        linked_styleguide:
          id: 5db981be9df2b3e1bfa19ef2
    color:
      summary: Color
      value:
        id: 5dbad85a76ea51c1f35b6f69
        source_id: 0BEBFEB3-A107-4D1D-A3B0-77D1FBD35F01
        created: 1517184000
        name: baby poop green
        r: 143
        g: 152
        b: 5
        a: 1
        variable_info:
          $ref: '#/components/examples/variableInfo/value'
        source:
          $ref: '#/components/examples/resourceSourceForProject/value'
    error:
      summary: Error
      value:
        message: Project is not found
    variableInfo:
      summary: Variable Info
      value:
        source_id: 280c52e619f9c84a4e5e265bb746ede50d898cb3
        collection_source_id: 4af2ee68305a9b4f0c655141e7ba01a51ab61bde
    entityReference:
      summary: Object Reference
      value:
        id: 5dbad85a76ea51c1f35b6f69
  responses:
    styleguideOrColorNotFound:
      description: Styleguide or color not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Styleguide not found:
              value:
                message: Styleguide not found
            Color not found:
              value:
                message: Color not found
    styleguideArchived:
      description: Styleguide archived response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Styleguide archived response:
              value:
                message: Styleguide is archived
    cannotCreateAColor:
      description: User cannot create a project color
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            User cannot create a project color:
              value:
                message: User with role member in a project cannot create a color
    projectOrColorNotFound:
      description: Project or color not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Project not found:
              value:
                message: Project not found
            Color not found:
              value:
                message: Color not found
    cannotUpdateAProjectColor:
      description: User cannot update a project color
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            User cannot update a project color:
              value:
                message: User with role alien in a project cannot update a color
    notAProjectMemberOrArchived:
      description: Not a project member or project archived
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Not a member:
              value:
                message: User is not a member of the project
            Project is archived:
              value:
                message: Project is archived
    projectNotFound:
      description: Project not found response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Project not found response:
              value:
                message: Project not found
    styleguideNotFound:
      description: Styleguide not found response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Styleguide not found response:
              value:
                message: Styleguide not found
    cannotUpdateAStyleguideColor:
      description: User cannot update a styleguide color
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            User cannot update a styleguide color:
              value:
                message: User with role alien in a styleguide cannot update a color
    cannotCreateAStyleguideColor:
      description: User cannot create a styleguide color
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            User cannot create a styleguide color:
              value:
                message: User with role alien in a styleguide cannot create a color
    notAStyleguideMemberOrArchived:
      description: Not a styleguide member or styleguide archived
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Not a member:
              value:
                message: User is not a member of the styleguide
            Styleguide is archived:
              value:
                message: Styleguide is archived
    noContent:
      description: Successful response
    projectArchived:
      description: Project archived response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Project archived response:
              value:
                message: Project is archived
  schemas:
    ColorCreateBody:
      title: Color Create Body
      required:
      - name
      - r
      - g
      - b
      - a
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the color
        source_id:
          type: string
          description: Color's identifier in the design tool
        r:
          type: integer
          minimum: 0
          maximum: 255
          description: Red component of the color
        g:
          type: integer
          minimum: 0
          maximum: 255
          description: Green component of the color
        b:
          type: integer
          minimum: 0
          maximum: 255
          description: Blue component of the color
        a:
          type: number
          minimum: 0
          maximum: 1
          description: Alpha component of the color
    ResourceProjectSource:
      title: Source Project
      type: object
      description: The source project of the resource
      required:
      - id
      - name
      - platform
      properties:
        id:
          type: string
          description: The unique id of the source project
        name:
          type: string
          description: The name of the source project
        platform:
          type: string
          enum:
          - web
          - ios
          - android
          - macos
          description: The target platform of the source project
        linked_styleguide:
          $ref: '#/components/schemas/EntityReference'
          description: Reference of the styleguide which the source project is linked to
      example:
        $ref: '#/components/examples/resourceProjectSource'
    EntityReference:
      title: Object Reference
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: Id of the entity
      example:
        $ref: '#/components/examples/entityReference'
    ErrorResponse:
      title: Error Response
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: A user readable descriptive message for the error
        detail:
          type: string
          description: A detailed message describing the error
        code:
          type: string
          description: The unique code for the error
      example:
        $ref: '#/components/examples/error'
    ResourceSource:
      title: Resource Source
      type: object
      description: Source details for resource. It has to be either `project` or `styleguide`.
      properties:
        project:
          $ref: '#/components/schemas/ResourceProjectSource'
        styleguide:
          $ref: '#/components/schemas/ResourceStyleguideSource'
      example:
        $ref: '#/components/examples/resourceSourceForProject'
      x-examples:
        Project:
          $ref: '#/components/examples/resourceSourceForProject'
        Styleguide:
          $ref: '#/components/examples/resourceSourceForStyleguide'
    VariableInfo:
      title: Variable Info
      type: object
      required:
      - source_id
      - collection_source_id
      properties:
        source_id:
          type: string
          description: The source id of the variable
        collection_source_id:
          type: string
          description: The source id of the collection that the variable belongs to
      example:
        $ref: '#/components/examples/variableInfo'
    Color:
      title: Color
      type: object
      required:
      - id
      - created
      - name
      - r
      - g
      - b
      - a
      properties:
        id:
          type: string
          description: Identifier of the color
        created:
          type: integer
          format: timestamp
          description: The unix timestamp when the color was created
        source_id:
          type: string
          description: Color's identifier in the design tool
        name:
          type: string
          description: Name of the color
        r:
          type: integer
          description: Red component of the color
        g:
          type: integer
          description: Green component of the color
        b:
          type: integer
          description: Blue component of the color
        a:
          type: number
          description: Alpha component of the color
        source:
          $ref: '#/components/schemas/ResourceSource'
          description: Source of the color–either `project` or `styleguide`.
        variable_info:
          $ref: '#/components/schemas/VariableInfo'
          description: Variable info of the color
      example:
        $ref: '#/components/examples/color'
    ResourceStyleguideSource:
      title: Source Styleguide
      type: object
      description: The source styleguide of the resource
      required:
      - id
      - name
      - platform
      properties:
        id:
          type: string
          description: The unique id of the source styleguide
        name:
          type: string
          description: The name of the source styleguide
        platform:
          type: string
          enum:
          - base
          - web
          - ios
          - android
          - macos
          description: The target platform of the source styleguide
        parent:
          $ref: '#/components/schemas/EntityReference'
          description: Reference of the parent styleguide of the source styleguide
      example:
        $ref: '#/components/examples/resourceStyleguideSource'
    ColorUpdateBody:
      title: Color Update Body
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the color
        r:
          type: integer
          minimum: 0
          maximum: 255
          description: Red component of the color
        g:
          type: integer
          minimum: 0
          maximum: 255
          description: Green component of the color
        b:
          type: integer
          minimum: 0
          maximum: 255
          description: Blue component of the color
        a:
          type: number
          minimum: 0
          maximum: 1
          description: Alpha component of the color
  parameters:
    linked_styleguide:
      name: linked_styleguide
      in: query
      description: Reference styleguide id
      required: false
      schema:
        type: string
        pattern: /^[0-9a-f]{24}$/i
    limit:
      name: limit
      in: query
      description: Pagination limit
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 30
    offset:
      name: offset
      in: query
      description: Pagination offset
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    linked_project:
      name: linked_project
      in: query
      description: Reference project id
      required: false
      schema:
        type: string
        pattern: /^[0-9a-f]{24}$/i
    project_id:
      name: project_id
      in: path
      description: Project id
      required: true
      schema:
        type: string
        pattern: /^[0-9a-f]{24}$/i
    include_linked_styleguides:
      name: include_linked_styleguides
      in: query
      description: Whether to include linked styleguides or not
      required: false
      schema:
        type: boolean
        default: false
    styleguide_id:
      name: styleguide_id
      in: path
      description: Styleguide id
      required: true
      schema:
        type: string
        pattern: /^[0-9a-f]{24}$/i
    color_id:
      name: color_id
      in: path
      description: Color id
      required: true
      schema:
        type: string
        pattern: /^[0-9a-f]{24}$/i
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /v1/oauth/authorize
          tokenUrl: /v1/oauth/token
          refreshUrl: /v1/oauth/token
          scopes: {}
    PersonalAccessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT