Department of Better Technology

Department of Better Technology Responses API

Create, read, update, trash, and recover form submissions.

GitHub OpenAPI

Operations 7

GET /projects/{project_id}/responses List responses #
POST /projects/{project_id}/responses Create a response #
GET /projects/{project_id}/responses/{response_id} Retrieve a response #
PUT /projects/{project_id}/responses/{response_id} Update a response #
DELETE /projects/{project_id}/responses/{response_id} Move a response to trash #
POST /projects/{project_id}/responses/{response_id}/recover Recover a response from trash #
DELETE /projects/{project_id}/responses/{response_id}/delete_forever Permanently delete a response #

Documentation

📖
Authentication
https://artifacts.apis.io/department-of-better-technology/authentication/department-of-better-technology-authentication.yml

Specifications

⚙
OpenAPI
https://artifacts.apis.io/department-of-better-technology/openapi/department-of-better-technology-responses-api-openapi.yml

Other Resources

🔗
Conventions
https://artifacts.apis.io/department-of-better-technology/conventions/department-of-better-technology-conventions.yml
🔗
ErrorCatalog
https://artifacts.apis.io/department-of-better-technology/errors/department-of-better-technology-problem-types.yml
🔗
DataModel
https://artifacts.apis.io/department-of-better-technology/data-model/department-of-better-technology-data-model.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/department-of-better-technology:department-of-better-technology-responses-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

department-of-better-technology-responses-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Screendoor Responses 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: Responses
  description: Create, read, update, trash, and recover form submissions.
paths:
  /projects/{project_id}/responses:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listResponses
      summary: List responses
      description: Returns a paginated list of a project's responses (submissions).
      tags:
      - Responses
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - name: sort
        in: query
        description: Field to sort by.
        schema:
          type: string
      - name: direction
        in: query
        description: Sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: trash
        in: query
        description: Return trashed responses instead of active ones.
        schema:
          type: boolean
      - name: advanced_search
        in: query
        description: Advanced search query string.
        schema:
          type: string
      responses:
        '200':
          description: A paginated list of responses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createResponse
      summary: Create a response
      description: Submits a new response to a project's form.
      tags:
      - Responses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseWrite'
      responses:
        '201':
          description: The created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseDetailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /projects/{project_id}/responses/{response_id}:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    - $ref: '#/components/parameters/ResponseId'
    get:
      operationId: getResponse
      summary: Retrieve a response
      description: Returns a single response, optionally in a detailed format.
      tags:
      - Responses
      parameters:
      - name: response_format
        in: query
        description: Use `detailed` to include assignees, archived responses, and more.
        schema:
          type: string
          enum:
          - detailed
      responses:
        '200':
          description: The requested response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseDetailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateResponse
      summary: Update a response
      description: Updates the field values, status, or labels of a response.
      tags:
      - Responses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseWrite'
      responses:
        '200':
          description: The updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseDetailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: trashResponse
      summary: Move a response to trash
      description: Moves a response to the trash (recoverable).
      tags:
      - Responses
      responses:
        '204':
          description: The response was moved to trash.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/responses/{response_id}/recover:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    - $ref: '#/components/parameters/ResponseId'
    post:
      operationId: recoverResponse
      summary: Recover a response from trash
      description: Restores a trashed response.
      tags:
      - Responses
      responses:
        '200':
          description: The recovered response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/responses/{response_id}/delete_forever:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    - $ref: '#/components/parameters/ResponseId'
    delete:
      operationId: deleteResponseForever
      summary: Permanently delete a response
      description: Permanently deletes a response. This cannot be undone.
      tags:
      - Responses
      responses:
        '204':
          description: The response was permanently deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
    SubmissionSource:
      type: object
      properties:
        type:
          type: string
          example: frontend
        hostname:
          type: string
    ResponseDetailed:
      allOf:
      - $ref: '#/components/schemas/Response'
      - type: object
        properties:
          archived_responses:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                responses_updated_at:
                  type: string
                  format: date-time
                responses:
                  type: object
          assignees:
            type: array
            items:
              $ref: '#/components/schemas/Assignee'
    Response:
      type: object
      properties:
        id:
          type: integer
        sequential_id:
          type: integer
        project_id:
          type: integer
        form_id:
          type:
          - integer
          - 'null'
        initial_form_id:
          type:
          - integer
          - 'null'
        pretty_id:
          type: string
        submitted_at:
          type:
          - string
          - 'null'
          format: date-time
        responses:
          type: object
          description: Map of field id (string) to submitted value.
          additionalProperties: true
        rating_aggregates:
          type: object
        average_rating:
          type:
          - number
          - 'null'
        num_ratings:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        status:
          type: string
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ResponseLabel'
        user:
          type:
          - object
          - 'null'
        submission_source:
          $ref: '#/components/schemas/SubmissionSource'
    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
    ResponseWrite:
      type: object
      properties:
        response_fields:
          type: object
          description: Map of field id (string) to submitted value.
          additionalProperties: true
        status:
          type: string
        labels:
          type: array
          items:
            type: string
        skip_email_confirmation:
          type: boolean
        skip_notifications:
          type: boolean
        skip_validation:
          type: boolean
        force_validation:
          type: boolean
    Assignee:
      type: object
      properties:
        type:
          type: string
          enum:
          - User
          - Team
        id:
          type: integer
        name:
          type: string
    ResponseLabel:
      type: object
      properties:
        name:
          type: string
        color:
          type: string
  parameters:
    ResponseId:
      name: response_id
      in: path
      required: true
      description: The id of the response.
      schema:
        type: integer
    PerPage:
      name: per_page
      in: query
      description: The number of records per page (max 100).
      schema:
        type: integer
        default: 25
        maximum: 100
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The id of the project.
      schema:
        type: integer
    Page:
      name: page
      in: query
      description: The page of results to return.
      schema:
        type: integer
        default: 1
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The API key is missing or invalid.
      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'
  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.