openapi: 3.0.3
info:
  title: 'Stylus API'
  description: "Programmatic read access to your team's style guides."
  version: 1.0.0
servers:
  -
    url: 'http://localhost'
tags:
  -
    name: Endpoints
    description: ''
  -
    name: 'Style Guides'
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: "Generate a token from your team's settings page. Tokens may also be passed as `?key=<token>` for legacy compatibility."
security:
  -
    default: []
paths:
  /api/whoami:
    get:
      summary: ''
      operationId: getApiWhoami
      description: ''
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: unauthenticated
                    message: 'A valid API token is required.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: unauthenticated
                      message:
                        type: string
                        example: 'A valid API token is required.'
      tags:
        - Endpoints
      security: []
  /api/style-guides:
    get:
      summary: 'List style guides for the authenticated team.'
      operationId: listStyleGuidesForTheAuthenticatedTeam
      description: "Returns every style guide owned by the calling team, including sections, rules,\nglossary terms, preferred spellings, and inheritance."
      parameters: []
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1
                    external_name:
                      type: string
                      example: 'Brand Guide'
                    uuid:
                      type: string
                      example: 550e8400-e29b-41d4-a716-446655440000
                    sections:
                      type: array
                      example: []
                    glossary_terms:
                      type: array
                      example: []
                    preferred_spellings:
                      type: array
                      example: []
                    inherited_style_guides:
                      type: array
                      example: []
                example:
                  -
                    id: 1
                    external_name: 'Brand Guide'
                    uuid: 550e8400-e29b-41d4-a716-446655440000
                    sections: []
                    glossary_terms: []
                    preferred_spellings: []
                    inherited_style_guides: []
      tags:
        - 'Style Guides'
  /api/style-guides/list:
    get:
      summary: 'List style guide summaries.'
      operationId: listStyleGuideSummaries
      description: 'Returns just `id`, `external_name`, and `uuid` for each guide on the team.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1
                    external_name:
                      type: string
                      example: 'Brand Guide'
                    uuid:
                      type: string
                      example: 550e8400-e29b-41d4-a716-446655440000
                example:
                  -
                    id: 1
                    external_name: 'Brand Guide'
                    uuid: 550e8400-e29b-41d4-a716-446655440000
      tags:
        - 'Style Guides'
  '/api/style-guides/{uuid}':
    get:
      summary: 'Get a single style guide by UUID.'
      operationId: getASingleStyleGuideByUUID
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  id: 1
                  external_name: Brand
                  uuid: 550e8400-e29b-41d4-a716-446655440000
                  sections: []
                  inherited_style_guides: []
                properties:
                  id:
                    type: integer
                    example: 1
                  external_name:
                    type: string
                    example: Brand
                  uuid:
                    type: string
                    example: 550e8400-e29b-41d4-a716-446655440000
                  sections:
                    type: array
                    example: []
                  inherited_style_guides:
                    type: array
                    example: []
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Style guide not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Style guide not found.'
      tags:
        - 'Style Guides'
    parameters:
      -
        in: path
        name: uuid
        description: "The guide's UUID."
        example: 550e8400-e29b-41d4-a716-446655440000
        required: true
        schema:
          type: string
  '/api/style-guides/{uuid}/validate':
    get:
      summary: 'Validate that a UUID corresponds to a guide the caller can access.'
      operationId: validateThatAUUIDCorrespondsToAGuideTheCallerCanAccess
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                properties:
                  success:
                    type: boolean
                    example: true
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: 'Style guide not found.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Style guide not found.'
      tags:
        - 'Style Guides'
    parameters:
      -
        in: path
        name: uuid
        description: "The guide's UUID."
        example: 6ff8f7f6-1eb3-3525-be4a-3932c805afed
        required: true
        schema:
          type: string
  /api/public-guides:
    get:
      summary: 'List public style guides.'
      operationId: listPublicStyleGuides
      description: 'No authentication required. Returns guides explicitly marked public by their team.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1
                    external_name:
                      type: string
                      example: 'Public Demo'
                    uuid:
                      type: string
                      example: 550e8400-e29b-41d4-a716-446655440000
                example:
                  -
                    id: 1
                    external_name: 'Public Demo'
                    uuid: 550e8400-e29b-41d4-a716-446655440000
      tags:
        - 'Style Guides'
      security: []
