openapi: 3.0.3
info:
  title: Screendoor Files Statuses 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: Statuses
  description: Manage the status workflow stages for a project's responses.
paths:
  /projects/{project_id}/statuses:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listStatuses
      summary: List statuses
      description: Returns the status workflow stages for a project.
      tags:
      - Statuses
      responses:
        '200':
          description: A list of statuses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Status'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createStatus
      summary: Create a status
      description: Adds a new status to the project's workflow.
      tags:
      - Statuses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
      responses:
        '201':
          description: The created status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /projects/{project_id}/statuses/reorder:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: reorderStatuses
      summary: Reorder statuses
      description: Sets the order of a project's statuses.
      tags:
      - Statuses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - names
              properties:
                names:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: The reordered list of statuses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Status'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /projects/{project_id}/statuses/{name}:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    - $ref: '#/components/parameters/PathName'
    get:
      operationId: getStatus
      summary: Retrieve a status
      description: Returns a single status by name.
      tags:
      - Statuses
      responses:
        '200':
          description: The requested status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateStatus
      summary: Update a status
      description: Renames a status.
      tags:
      - Statuses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '200':
          description: The updated status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: deleteStatus
      summary: Delete a status
      description: Removes a status from the project's workflow.
      tags:
      - Statuses
      responses:
        '204':
          description: The status was deleted.
        '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
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The id of the project.
      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
    Status:
      type: object
      properties:
        name:
          type: string
        responses_count:
          type: integer
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
  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.