openapi: 3.0.3
info:
  title: Screendoor Files Response Labels API
  description: The Screendoor API from the Department of Better Technology (CityBase Screendoor) lets you programmatically manage online forms, submissions ("responses"), evaluation workflows, statuses, labels, and assignments. Screendoor is used by government agencies and organizations to build paperless forms and manage intake, review, and approval processes. All endpoints are relative to the base URL and authenticated with an API key passed as the `api_key` URL parameter.
  version: '1'
  contact:
    name: Department of Better Technology (CityBase)
    url: https://help.dobt.co/
  x-api-version-header: 'Api-Version: 1'
  x-provenance:
    generated: '2026-07-18'
    method: generated
    source: https://dobtco.github.io/screendoor-api-docs/
servers:
- url: https://screendoor.dobt.co/api
  description: Screendoor production API
security:
- apiKeyAuth: []
tags:
- name: Response Labels
  description: Attach or detach labels on an individual response.
paths:
  /responses/{response_id}/labels:
    parameters:
    - $ref: '#/components/parameters/ResponseId'
    get:
      operationId: listResponseLabels
      summary: List a response's labels
      tags:
      - Response Labels
      responses:
        '200':
          description: The labels on the response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseLabel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: addResponseLabels
      summary: Add labels to a response
      tags:
      - Response Labels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelNames'
      responses:
        '200':
          description: The updated set of labels.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseLabel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    put:
      operationId: replaceResponseLabels
      summary: Replace a response's labels
      tags:
      - Response Labels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelNames'
      responses:
        '200':
          description: The replaced set of labels.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseLabel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: removeAllResponseLabels
      summary: Remove all labels from a response
      tags:
      - Response Labels
      responses:
        '204':
          description: All labels were removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /responses/{response_id}/labels/{name}:
    parameters:
    - $ref: '#/components/parameters/ResponseId'
    - $ref: '#/components/parameters/PathName'
    delete:
      operationId: removeResponseLabel
      summary: Remove a label from a response
      tags:
      - Response Labels
      responses:
        '204':
          description: The label was removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    PathName:
      name: name
      in: path
      required: true
      description: The name of the resource (URL-encoded).
      schema:
        type: string
    ResponseId:
      name: response_id
      in: path
      required: true
      description: The id of the response.
      schema:
        type: integer
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The request was well-formed but failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
  schemas:
    ValidationError:
      type: object
      properties:
        error:
          type: string
        errors:
          type: object
          description: Map of field name to an array of validation messages.
          additionalProperties:
            type: array
            items:
              type: string
    LabelNames:
      type: object
      required:
      - labels
      properties:
        labels:
          type: array
          items:
            type: string
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
    ResponseLabel:
      type: object
      properties:
        name:
          type: string
        color:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: Your Screendoor API key, obtained in Screendoor under Settings -> API Keys, passed as the `api_key` URL parameter on every request.