HM Courts & Tribunals Service

HM Courts & Tribunals Service Admin API

Administrative operations such as jobs can be run from this set of endpoints.

Documentation GitHub OpenAPI

Operations 5

GET /admin/jobs/{jobType} Get the status of a background job being processed in an administrative context #

PUT /admin/jobs/{jobType} Enable/Disable a database job by its name #

GET /admin/jobs/{jobType}/retention-policy Get a database job retention period by its name #

PUT /admin/jobs/{jobType}/retention-policy Update a database job retention period by its name #

POST /admin/csds/trigger Trigger CSDS ingress on demand #

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/hmcts:hmcts-admin-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

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

openapi: 3.2.0
info:
  title: Hmcts Admin API
  version: '@version@'
  contact:
    name: HMCTS AppReg Team
    url: https://github.com/hmcts/appreg-api
  description: 'Operations tagged admin across 2 of this provider''s published API definitions: appreg-api-openapi.yaml, hmcts-applications-register-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /
tags:
- description: Administrative operations such as jobs can be run from this set of endpoints.
  name: Admin
paths:
  /admin/jobs/{jobType}:
    get:
      description: Returns the current status and details of a background job.
      operationId: getJobStatus
      parameters:
      - description: The type of the job we are determining the status of.
        in: path
        name: jobType
        required: true
        schema:
          $ref: '#/components/schemas/admin-job-type'
      responses:
        '200':
          content:
            application/vnd.hmcts.appreg.v1+json:
              schema:
                $ref: '#/components/schemas/admin-job-status'
          description: Job status retrieved successfully.
          headers:
            Vary:
              description: Response varies by Accept for media-type versioning.
              example: Accept
              schema:
                type: string
        '401':
          content:
            application/problem+json:
              examples:
                unauthenticated:
                  value:
                    type: https://errors.hmcts.net/common/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid credentials
              schema:
                $ref: '#/components/schemas/problem'
          description: Authentication required or token invalid.
        '409':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/conflict
                    title: Conflict
                    status: 409
                    detail: The Application List could not be modified due to a conflict with its current state
              schema:
                $ref: '#/components/schemas/problem'
          description: Conflict with the current state of the resource.
        '403':
          content:
            application/problem+json:
              examples:
                forbidden:
                  value:
                    type: https://errors.hmcts.net/common/forbidden
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to access this resource
              schema:
                $ref: '#/components/schemas/problem'
          description: Authenticated but not permitted to perform this action.
        '404':
          content:
            application/problem+json:
              examples:
                missing:
                  value:
                    type: https://errors.hmcts.net/appreg/not-found
                    title: Not Found
                    status: 404
                    detail: Result code with id=123 was not found
              schema:
                $ref: '#/components/schemas/problem'
          description: The requested resource was not found.
        '500':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/problem'
          description: Unexpected server error.
      summary: Get the status of a background job being processed in an administrative context
      tags:
      - Admin
    put:
      description: Enables or disables a database job by its name.
      operationId: enableDisableDatabaseJobByName
      parameters:
      - description: The name of the database job to trigger.
        example: APPLICATION_LISTS_DATABASE_JOB
        in: path
        name: jobType
        required: true
        schema:
          $ref: '#/components/schemas/admin-job-type'
      - description: Flag to enable (true) or disable (false) the database job.
        example: true
        in: query
        name: enable
        required: true
        schema:
          type: boolean
      responses:
        '200':
          description: Job enabled/disabled successfully.
        '401':
          content:
            application/problem+json:
              examples:
                unauthenticated:
                  value:
                    type: https://errors.hmcts.net/common/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid credentials
              schema:
                $ref: '#/components/schemas/problem'
          description: Authentication required or token invalid.
        '403':
          content:
            application/problem+json:
              examples:
                forbidden:
                  value:
                    type: https://errors.hmcts.net/common/forbidden
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to access this resource
              schema:
                $ref: '#/components/schemas/problem'
          description: Authenticated but not permitted to perform this action.
        '404':
          content:
            application/problem+json:
              examples:
                missing:
                  value:
                    type: https://errors.hmcts.net/appreg/not-found
                    title: Not Found
                    status: 404
                    detail: Result code with id=123 was not found
              schema:
                $ref: '#/components/schemas/problem'
          description: The requested resource was not found.
        '500':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/problem'
          description: Unexpected server error.
      summary: Enable/Disable a database job by its name
      tags:
      - Admin
    servers:
    - url: /
  /admin/jobs/{jobType}/retention-policy:
    get:
      description: Returns the RETENTION_PERIOD_DAYS configuration for the specified database job.
      operationId: getDatabaseJobRetentionPeriodByName
      parameters:
      - description: The name of the database job to read.
        example: APPLICATION_LISTS_DATABASE_JOB
        in: path
        name: jobType
        required: true
        schema:
          $ref: '#/components/schemas/admin-job-type'
      responses:
        '200':
          content:
            application/vnd.hmcts.appreg.v1+json:
              schema:
                $ref: '#/components/schemas/job-retention-policy'
          description: Retention period retrieved successfully.
          headers:
            Vary:
              description: Response varies by Accept for media-type versioning.
              example: Accept
              schema:
                type: string
        '401':
          content:
            application/problem+json:
              examples:
                unauthenticated:
                  value:
                    type: https://errors.hmcts.net/common/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid credentials
              schema:
                $ref: '#/components/schemas/problem'
          description: Authentication required or token invalid.
        '403':
          content:
            application/problem+json:
              examples:
                forbidden:
                  value:
                    type: https://errors.hmcts.net/common/forbidden
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to access this resource
              schema:
                $ref: '#/components/schemas/problem'
          description: Authenticated but not permitted to perform this action.
        '404':
          content:
            application/problem+json:
              examples:
                missing:
                  value:
                    type: https://errors.hmcts.net/appreg/not-found
                    title: Not Found
                    status: 404
                    detail: Result code with id=123 was not found
              schema:
                $ref: '#/components/schemas/problem'
          description: The requested resource was not found.
        '500':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/problem'
          description: Unexpected server error.
      summary: Get a database job retention period by its name
      tags:
      - Admin
    put:
      description: Updates the RETENTION_PERIOD_DAYS configuration for the specified database job.
      operationId: updateDatabaseJobRetentionPeriodByName
      parameters:
      - description: The name of the database job to update.
        example: APPLICATION_LISTS_DATABASE_JOB
        in: path
        name: jobType
        required: true
        schema:
          $ref: '#/components/schemas/admin-job-type'
      - description: Number of days to retain closed application lists before deletion.
        example: 1825
        in: query
        name: retentionPeriodDays
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: Retention period updated successfully.
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
          description: Invalid request parameters.
        '401':
          content:
            application/problem+json:
              examples:
                unauthenticated:
                  value:
                    type: https://errors.hmcts.net/common/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid credentials
              schema:
                $ref: '#/components/schemas/problem'
          description: Authentication required or token invalid.
        '403':
          content:
            application/problem+json:
              examples:
                forbidden:
                  value:
                    type: https://errors.hmcts.net/common/forbidden
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to access this resource
              schema:
                $ref: '#/components/schemas/problem'
          description: Authenticated but not permitted to perform this action.
        '404':
          content:
            application/problem+json:
              examples:
                missing:
                  value:
                    type: https://errors.hmcts.net/appreg/not-found
                    title: Not Found
                    status: 404
                    detail: Result code with id=123 was not found
              schema:
                $ref: '#/components/schemas/problem'
          description: The requested resource was not found.
        '500':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/problem'
          description: Unexpected server error.
      summary: Update a database job retention period by its name
      tags:
      - Admin
    servers:
    - url: /
  /admin/csds/trigger:
    post:
      description: Runs all enabled CSDS ingress processors synchronously using the same retrieval and apply flow as the scheduled CSDS job. Processing continues if an individual processor fails, but the request returns an error after all processors have been attempted. Invalid record data returned by CSDS results in `502 Bad Gateway`; unexpected AppReg failures result in `500 Internal Server Error`. The endpoint does not update the scheduled-run execution log and therefore does not suppress a subsequent scheduled run. Only callers with the admin role can trigger the operation.
      operationId: triggerCsdsIngress
      responses:
        '200':
          description: All enabled CSDS ingress processors completed successfully.
          headers:
            Vary:
              description: Response varies by Accept for media-type versioning.
              example: Accept
              schema:
                type: string
        '401':
          content:
            application/problem+json:
              examples:
                unauthenticated:
                  value:
                    type: https://errors.hmcts.net/common/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid credentials
              schema:
                $ref: '#/components/schemas/problem'
          description: Authentication required or token invalid.
        '403':
          content:
            application/problem+json:
              examples:
                forbidden:
                  value:
                    type: https://errors.hmcts.net/common/forbidden
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to access this resource
              schema:
                $ref: '#/components/schemas/problem'
          description: Authenticated but not permitted to perform this action.
        '423':
          content:
            application/problem+json:
              examples:
                locked:
                  value:
                    type: https://errors.hmcts.net/common/locked
                    title: Locked
                    status: 423
                    detail: The CSDS ingest is already running
              schema:
                $ref: '#/components/schemas/problem'
          description: The requested operation could not start because the resource is locked.
        '500':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/problem'
          description: Unexpected server error.
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
          description: CSDS returned record data that is incompatible with the selected ingress processor.
      summary: Trigger CSDS ingress on demand
      tags:
      - Admin
    servers:
    - url: /
components:
  schemas:
    admin-job-status:
      description: Details of the database job status.
      properties:
        lastRan:
          description: The last time the job was run.
          format: date-time
          type: string
        enabled:
          description: Whether the job is currently enabled.
          example: true
          type: boolean
      type: object
    job-retention-policy:
      additionalProperties: false
      description: Retention policy configuration for an administrative background job.
      properties:
        retentionPeriodDays:
          description: Number of days to retain closed application lists before deletion.
          example: 1825
          minimum: 1
          type: integer
      type: object
    problem:
      description: RFC 9457/7807 problem details.
      properties:
        type:
          description: Problem type identifier (URI).
          example: https://errors.hmcts.net/appreg/bad-request
          format: uri
          type: string
        title:
          description: Short, human-readable summary.
          example: Invalid request parameters
          type: string
        status:
          description: HTTP status code.
          example: 400
          format: int32
          type: integer
        detail:
          description: Human-readable explanation specific to this occurrence.
          example: startDateFrom must be on or before startDateTo
          type: string
        instance:
          description: URI reference to the specific occurrence (if applicable).
          example: urn:request:2f9c3d8a-1b3a-4a1e-9b7f-6b2a6a0a2b2f
          format: uri
          type: string
        correlationId:
          description: Server-side correlation ID for tracing.
          example: 3e1a2c95a7d84a5fb3e1a2c95a7d84a5
          type: string
      required:
      - status
      - title
      - type
      type: object
    admin-job-type:
      description: The type of the administrative background job
      enum:
      - APPLICATION_LISTS_DATABASE_JOB
      - REFRESH_REFERENCE_DATA
      example: APPLICATION_LISTS_DATABASE_JOB
      type: string
x-refined-from:
- appreg-api-openapi.yaml
- hmcts-applications-register-openapi.yml

HM Courts & Tribunals Service Admin API

Operations 5

Specifications

SDKs

Schemas & Data

Other Resources