This section documents the REST API endpoints available in DiracX. The route documentation is automatically generated from the OpenAPI specification.

DiracX provides comprehensive REST API documentation through multiple formats:

Route Documentation (this section) - Human-readable documentation with request/response examples

When running a DiracX instance, you can also access:

Interactive Documentation (Swagger UI) at /api/docs - Try the API endpoints directly in your browser
OpenAPI Specification at /api/openapi.json - Machine-readable API schema for tools and clients

If you're looking for documentation on building routes (the Python infrastructure), see:

Router Infrastructure - Dependencies, factory functions, access policies
Adding a New Route - Tutorial for creating new API endpoints

Dirac 0.1.0

.well-known

GET /.well-known/openid-configuration

Get Openid Configuration

Description

OpenID Connect discovery endpoint.

Response 200 OK

application/json

⚠️ This example has been generated automatically href="#__codelineno-0-1">{ "issuer": "string", "token_endpoint": "string", "userinfo_endpoint": "string", "authorization_endpoint": "string", "device_authorization_endpoint": "string", "revocation_endpoint": "string", "jwks_uri": "string", "grant_types_supported": [ "string" ], "scopes_supported": [ "string" ], "response_types_supported": [ "string" ], "token_endpoint_auth_signing_alg_values_supported": [ "string" ], "token_endpoint_auth_methods_supported": [ "string" ], "code_challenge_methods_supported": [ "string" ] } from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "issuer": {
            "type": "string",
            "title": "Issuer"
        },
        "token_endpoint": {
            "type": "string",
            "title": "Token Endpoint"
        },
        "userinfo_endpoint": {
            "type": "string",
            "title": "Userinfo Endpoint"
        },
        "authorization_endpoint": {
            "type": "string",
            "title": "Authorization Endpoint"
        },
        "device_authorization_endpoint": {
            "type": "string",
            "title": "Device Authorization Endpoint"
        },
        "revocation_endpoint": {
            "type": "string",
            "title": "Revocation Endpoint"
        },
        "jwks_uri": {
            "type": "string",
            "title": "Jwks Uri"
        },
        "grant_types_supported": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Grant Types Supported"
        },
        "scopes_supported": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Scopes Supported"
        },
        "response_types_supported": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Response Types Supported"
        },
        "token_endpoint_auth_signing_alg_values_supported": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Token Endpoint Auth Signing Alg Values Supported"
        },
        "token_endpoint_auth_methods_supported": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Token Endpoint Auth Methods Supported"
        },
        "code_challenge_methods_supported": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Code Challenge Methods Supported"
        }
    },
    "type": "object",
    "required": [
        "issuer",
        "token_endpoint",
        "userinfo_endpoint",
        "authorization_endpoint",
        "device_authorization_endpoint",
        "revocation_endpoint",
        "jwks_uri",
        "grant_types_supported",
        "scopes_supported",
        "response_types_supported",
        "token_endpoint_auth_signing_alg_values_supported",
        "token_endpoint_auth_methods_supported",
        "code_challenge_methods_supported"
    ],
    "title": "OpenIDConfiguration"
}

GET /.well-known/jwks.json

Get Jwks

Description

Get the JWKs (public keys).

Response 200 OK

application/json

Schema of the response body

{
    "additionalProperties": true,
    "type": "object",
    "title": "Response .Well-Known Get Jwks"
}

GET /.well-known/dirac-metadata

Get Installation Metadata

Description

Get metadata about the dirac installation.

Response 200 OK

application/json

{
    "virtual_organizations": {}
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "virtual_organizations": {
            "additionalProperties": {
                "$ref": "#/components/schemas/VOInfo"
            },
            "type": "object",
            "title": "Virtual Organizations"
        }
    },
    "type": "object",
    "required": [
        "virtual_organizations"
    ],
    "title": "Metadata"
}

GET /.well-known/security.txt

Get Security Txt

Description

Get the security.txt file.

Response 200 OK

application/json

"string"

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string",
    "title": "Response .Well-Known Get Security Txt"
}

auth

POST /api/auth/device

Initiate Device Flow

Description

Initiate the device flow against DIRAC authorization Server.

Scope details: - If only VO is provided: Uses the default group and its properties for the VO.

If VO and group are provided: Uses the specified group and its properties for the VO.
If VO and properties are provided: Uses the default group and combines its properties with the provided properties.
If VO, group, and properties are provided: Uses the specified group and combines its properties with the provided properties.

Offers the user to go with the browser to auth/<vo>/device?user_code=XYZ

Input parameters

Parameter	In	Type	Default	Nullable	Description
`client_id`	query	string		No
`scope`	query	string		No

Response 200 OK

application/json

{
    "user_code": "string",
    "device_code": "string",
    "verification_uri_complete": "string",
    "verification_uri": "string",
    "expires_in": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "user_code": {
            "type": "string",
            "title": "User Code"
        },
        "device_code": {
            "type": "string",
            "title": "Device Code"
        },
        "verification_uri_complete": {
            "type": "string",
            "title": "Verification Uri Complete"
        },
        "verification_uri": {
            "type": "string",
            "title": "Verification Uri"
        },
        "expires_in": {
            "type": "integer",
            "title": "Expires In"
        }
    },
    "type": "object",
    "required": [
        "user_code",
        "device_code",
        "verification_uri_complete",
        "verification_uri",
        "expires_in"
    ],
    "title": "InitiateDeviceFlowResponse",
    "description": "Response for the device flow initiation."
}

GET /api/auth/device

Do Device Flow

Description

This is called as the verification URI for the device flow. It will redirect to the actual OpenID server (IAM, CheckIn) to perform a authorization code flow.

We set the user_code obtained from the device flow in a cookie to be able to map the authorization flow with the corresponding device flow. (note: it can't be put as parameter or in the URL)

Input parameters

Parameter	In	Type	Default	Nullable	Description
`user_code`	query	string		No

Response 200 OK

application/json

Schema of the response body

GET /api/auth/device/complete

Finish Device Flow

Description

This the url callbacked by IAM/CheckIn after the authorization flow was granted. It gets us the code we need for the authorization flow, and we can map it to the corresponding device flow using the user_code in the cookie/session.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`code`	query	string		No
`state`	query	string		No

Response 200 OK

application/json

Schema of the response body

GET /api/auth/device/complete/finished

Finished

Description

This is the final step of the device flow.

Response 200 OK

application/json

Schema of the response body

GET /api/auth/refresh-tokens

Get Refresh Tokens

Description

Get all refresh tokens for the user. If the user has the proxy_management property, then the subject is not used to filter the refresh tokens.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No

Response 200 OK

application/json

[
    null
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "items": {},
    "type": "array",
    "title": "Response Auth Get Refresh Tokens"
}

POST /api/auth/revoke

Revoke Refresh Token By Refresh Token

Description

Revoke a refresh token. Closely follows RFC 7009 (or try to, at least).

Request body

application/x-www-form-urlencoded

{
    "token": "string",
    "token_type_hint": "string",
    "client_id": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "token": {
            "type": "string",
            "title": "Token",
            "description": "The refresh token to revoke"
        },
        "token_type_hint": {
            "anyOf": [
                {
                    "type": "string"
                }
            ],
            "title": "Token Type Hint",
            "description": "Hint for the type of token being revoked",
            "nullable": true,
            "type": "string"
        },
        "client_id": {
            "type": "string",
            "title": "Client Id",
            "description": "The client ID of the application requesting the revocation",
            "default": "myDIRACClientID"
        }
    },
    "type": "object",
    "required": [
        "token"
    ],
    "title": "Body_auth_revoke_refresh_token_by_refresh_token"
}

Response 200 OK

application/json

"string"

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string",
    "title": "Response Auth Revoke Refresh Token By Refresh Token"
}

DELETE /api/auth/refresh-tokens/{jti}

Revoke Refresh Token By Jti

Description

Revoke a refresh token. If the user has the proxy_management property, then the subject is not used to filter the refresh tokens.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No
`jti`	path	string		No

Response 200 OK

application/json

"string"

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string",
    "title": "Response Auth Revoke Refresh Token By Jti"
}

GET /api/auth/userinfo

Userinfo

Description

Get information about the user's identity.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No

Response 200 OK

application/json

{
    "sub": "string",
    "vo": "string",
    "dirac_group": "string",
    "policies": {},
    "properties": [
        "string"
    ],
    "preferred_username": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "sub": {
            "type": "string",
            "title": "Sub"
        },
        "vo": {
            "type": "string",
            "title": "Vo"
        },
        "dirac_group": {
            "type": "string",
            "title": "Dirac Group"
        },
        "policies": {
            "additionalProperties": true,
            "type": "object",
            "title": "Policies"
        },
        "properties": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Properties"
        },
        "preferred_username": {
            "type": "string",
            "title": "Preferred Username"
        }
    },
    "type": "object",
    "required": [
        "sub",
        "vo",
        "dirac_group",
        "policies",
        "properties",
        "preferred_username"
    ],
    "title": "UserInfoResponse",
    "description": "Response for the userinfo endpoint."
}

GET /api/auth/authorize

Initiate Authorization Flow

Description

Initiate the authorization flow. It will redirect to the actual OpenID server (IAM, CheckIn) to perform a authorization code flow.

Scope details: - If only VO is provided: Uses the default group and its properties for the VO.

If VO and group are provided: Uses the specified group and its properties for the VO.
If VO and properties are provided: Uses the default group and combines its properties with the provided properties.
If VO, group, and properties are provided: Uses the specified group and combines its properties with the provided properties.

We set the user details obtained from the user authorize flow in a cookie to be able to map the authorization flow with the corresponding user authorize flow.

Input parameters

Parameter	In	Type	Nullable
`client_id`	query	string	No
`code_challenge`	query	string	No
`code_challenge_method`	query	string	No
`redirect_uri`	query	string	No
`response_type`	query	string	No
`scope`	query	string	No
`state`	query	string	No

Response 200 OK

application/json

Schema of the response body

GET /api/auth/authorize/complete

Complete Authorization Flow

Description

Complete the authorization flow.

The user is redirected back to the DIRAC auth service after completing the IAM's authorization flow. We retrieve the original flow details from the decrypted state and store the ID token requested from the IAM. The user is then redirected to the client's redirect URI.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`code`	query	string		No
`state`	query	string		No

Response 200 OK

application/json

Schema of the response body

POST /api/auth/token

Get Oidc Token

Description

Token endpoint to retrieve the token at the end of a flow. This is the endpoint being pulled by dirac-login when doing the device flow.

Request body

application/x-www-form-urlencoded

{
    "grant_type": null,
    "client_id": "string",
    "device_code": "string",
    "code": "string",
    "redirect_uri": "string",
    "code_verifier": "string",
    "refresh_token": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "grant_type": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "string"
                },
                {
                    "type": "string"
                }
            ],
            "title": "Grant Type",
            "description": "OAuth2 Grant type"
        },
        "client_id": {
            "type": "string",
            "title": "Client Id",
            "description": "OAuth2 client id"
        },
        "device_code": {
            "anyOf": [
                {
                    "type": "string"
                }
            ],
            "title": "Device Code",
            "description": "device code for OAuth2 device flow",
            "nullable": true,
            "type": "string"
        },
        "code": {
            "anyOf": [
                {
                    "type": "string"
                }
            ],
            "title": "Code",
            "description": "Code for OAuth2 authorization code flow",
            "nullable": true,
            "type": "string"
        },
        "redirect_uri": {
            "anyOf": [
                {
                    "type": "string"
                }
            ],
            "title": "Redirect Uri",
            "description": "redirect_uri used with OAuth2 authorization code flow",
            "nullable": true,
            "type": "string"
        },
        "code_verifier": {
            "anyOf": [
                {
                    "type": "string"
                }
            ],
            "title": "Code Verifier",
            "description": "Verifier for the code challenge for the OAuth2 authorization flow with PKCE",
            "nullable": true,
            "type": "string"
        },
        "refresh_token": {
            "anyOf": [
                {
                    "type": "string"
                }
            ],
            "title": "Refresh Token",
            "description": "Refresh token used with OAuth2 refresh token flow",
            "nullable": true,
            "type": "string"
        }
    },
    "type": "object",
    "required": [
        "grant_type",
        "client_id"
    ],
    "title": "Body_auth_get_oidc_token"
}

Response 200 OK

application/json

{
    "access_token": "string",
    "expires_in": 0,
    "token_type": "string",
    "refresh_token": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "access_token": {
            "type": "string",
            "title": "Access Token"
        },
        "expires_in": {
            "type": "integer",
            "title": "Expires In"
        },
        "token_type": {
            "type": "string",
            "title": "Token Type",
            "default": "Bearer"
        },
        "refresh_token": {
            "anyOf": [
                {
                    "type": "string"
                }
            ],
            "title": "Refresh Token",
            "nullable": true,
            "type": "string"
        }
    },
    "type": "object",
    "required": [
        "access_token",
        "expires_in"
    ],
    "title": "TokenResponse"
}

config

GET /api/config/

Serve Config

Description

Get the latest view of the config.

If If-None-Match header is given and matches the latest ETag, return 304

If If-Modified-Since is given and is newer than latest, return 304: this is to avoid flip/flopping

Input parameters

Parameter	In	Type	Default	Nullable
`OpenIdConnect`	header	string	N/A	No
`if-modified-since`	header	string		Yes
`if-none-match`	header	string		Yes

Response 200 OK

application/json

Schema of the response body

jobs

POST /api/jobs/sandbox

Initiate Sandbox Upload

Description

Get the PFN for the given sandbox, initiate an upload as required.

If the sandbox already exists in the database then the PFN is returned and there is no "url" field in the response.

If the sandbox does not exist in the database then the "url" and "fields" should be used to upload the sandbox to the storage backend.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No

Request body

application/json

{
    "checksum_algorithm": "sha256",
    "checksum": "string",
    "size": 0,
    "format": "tar.bz2"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "checksum_algorithm": {
            "$ref": "#/components/schemas/ChecksumAlgorithm"
        },
        "checksum": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{64}$",
            "title": "Checksum"
        },
        "size": {
            "type": "integer",
            "minimum": 1.0,
            "title": "Size"
        },
        "format": {
            "$ref": "#/components/schemas/SandboxFormat"
        }
    },
    "type": "object",
    "required": [
        "checksum_algorithm",
        "checksum",
        "size",
        "format"
    ],
    "title": "SandboxInfo"
}

Response 200 OK

application/json

{
    "pfn": "string",
    "url": "string",
    "fields": {}
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "pfn": {
            "type": "string",
            "title": "Pfn"
        },
        "url": {
            "anyOf": [
                {
                    "type": "string"
                }
            ],
            "title": "Url",
            "nullable": true,
            "type": "string"
        },
        "fields": {
            "additionalProperties": {
                "type": "string"
            },
            "type": "object",
            "title": "Fields",
            "default": {}
        }
    },
    "type": "object",
    "required": [
        "pfn"
    ],
    "title": "SandboxUploadResponse"
}

GET /api/jobs/sandbox

Get Sandbox File

Description

Get a presigned URL to download a sandbox file.

This route cannot use a redirect response most clients will also send the authorization header when following a redirect. This is not desirable as it would leak the authorization token to the storage backend. Additionally, most storage backends return an error when they receive an authorization header for a presigned URL.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No
`pfn`	query	string		No

Response 200 OK

application/json

{
    "url": "string",
    "expires_in": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "url": {
            "type": "string",
            "title": "Url"
        },
        "expires_in": {
            "type": "integer",
            "title": "Expires In"
        }
    },
    "type": "object",
    "required": [
        "url",
        "expires_in"
    ],
    "title": "SandboxDownloadResponse"
}

GET /api/jobs/{job_id}/sandbox

Get Job Sandboxes

Description

Get input and output sandboxes of given job.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No
`job_id`	path	integer		No

Response 200 OK

application/json

Schema of the response body

{
    "type": "object",
    "additionalProperties": {
        "type": "array",
        "items": {}
    },
    "title": "Response Jobs Get Job Sandboxes"
}

DELETE /api/jobs/{job_id}/sandbox

Unassign Job Sandboxes

Description

Delete single job sandbox mapping.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No
`job_id`	path	integer		No

Response 200 OK

application/json

Schema of the response body

GET /api/jobs/{job_id}/sandbox/{sandbox_type}

Get Job Sandbox

Description

Get input or output sandbox of given job.

Input parameters

Parameter	In	Type	Default	Nullable
`OpenIdConnect`	header	string	N/A	No
`job_id`	path	integer		No
`sandbox_type`	path	string		No

Response 200 OK

application/json

[
    null
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {},
    "title": "Response Jobs Get Job Sandbox"
}

PATCH /api/jobs/{job_id}/sandbox/output

Assign Sandbox To Job

Description

Map the pfn as output sandbox to job.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No
`job_id`	path	integer		No

Request body

application/json

"string"

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "string",
    "maxLength": 256,
    "pattern": "^(:?SB:[A-Za-z]+\\|)?/S3/[a-z0-9\\.\\-]{3,63}(?:/[^/]+){3}/[a-z0-9]{3,10}:[0-9a-f]{64}\\.[a-z0-9\\.]+$",
    "title": "Pfn"
}

Response 200 OK

application/json

Schema of the response body

POST /api/jobs/sandbox/unassign

Unassign Bulk Jobs Sandboxes

Description

Delete bulk jobs sandbox mapping.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No

Request body

application/json

{
    "job_ids": [
        1,
        2,
        3
    ]
}

{
    "job_ids": [
        1
    ]
}

Schema of the request body

{
    "properties": {
        "job_ids": {
            "items": {
                "type": "integer"
            },
            "type": "array",
            "title": "Job Ids"
        }
    },
    "type": "object",
    "required": [
        "job_ids"
    ],
    "title": "Body_jobs_unassign_bulk_jobs_sandboxes"
}

Response 204 No Content

PATCH /api/jobs/status

Set Job Statuses

Description

Set the status of a job or a list of jobs.

Body parameters: - Status: The new status of the job. - MinorStatus: The minor status of the job. - ApplicationStatus: The application-specific status of the job. - Source: The source of the status update (default is "Unknown").

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No
`force`	query	boolean	False	No

Request body

application/json

{
    "1": {
        "2025-11-09 03:01:18.683546+00:00": {
            "Status": "Killed",
            "MinorStatus": "Marked as killed",
            "ApplicationStatus": "Job was killed by user",
            "Source": "User"
        }
    },
    "2": {
        "2025-11-09 03:01:18.683556+00:00": {
            "Status": "Failed",
            "MinorStatus": "Timeout"
        }
    }
}

{
    "<job_id>": {
        "<timestamp>": {
            "Status": "<status>",
            "MinorStatus": "<minor_status>",
            "ApplicationStatus": "<application_status>",
            "Source": "<source>"
        }
    }
}

Schema of the request body

{
    "type": "object",
    "additionalProperties": {
        "type": "object",
        "additionalProperties": {
            "$ref": "#/components/schemas/JobStatusUpdate"
        }
    },
    "title": "Job Update"
}

Response 200 OK

application/json

{
    "success": {},
    "failed": {}
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "success": {
            "additionalProperties": {
                "$ref": "#/components/schemas/SetJobStatusReturnSuccess"
            },
            "type": "object",
            "title": "Success"
        },
        "failed": {
            "additionalProperties": {
                "additionalProperties": {
                    "type": "string"
                },
                "type": "object"
            },
            "type": "object",
            "title": "Failed"
        }
    },
    "type": "object",
    "required": [
        "success",
        "failed"
    ],
    "title": "SetJobStatusReturn"
}

PATCH /api/jobs/heartbeat

Add Heartbeat

Description

Register a heartbeat from the job.

This endpoint is used by the JobAgent to send heartbeats to the WMS and to receive job commands from the WMS. It also results in stalled jobs being restored to the RUNNING status.

The data parameter and return value are mappings keyed by job ID.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No

Request body

application/json

{
    "1": {
        "LoadAverage": 2.5,
        "MemoryUsed": 1024.0,
        "Vsize": 2048.0,
        "AvailableDiskSpace": 500.0,
        "CPUConsumed": 75.0,
        "WallClockTime": 3600.0,
        "StandardOutput": "Job is running smoothly."
    },
    "2": {
        "LoadAverage": 1.0,
        "MemoryUsed": 512.0,
        "Vsize": 1024.0,
        "AvailableDiskSpace": 250.0,
        "CPUConsumed": 50.0,
        "WallClockTime": 1800.0,
        "StandardOutput": "Job is waiting for resources."
    }
}

{
    "<job_id>": {
        "LoadAverage": 2.5,
        "MemoryUsed": 1024.0,
        "Vsize": 2048.0,
        "AvailableDiskSpace": 500.0,
        "CPUConsumed": 75.0,
        "WallClockTime": 3600.0,
        "StandardOutput": "Job is running smoothly."
    }
}

Schema of the request body

{
    "additionalProperties": {
        "$ref": "#/components/schemas/HeartbeatData"
    },
    "type": "object",
    "title": "Data"
}

Response 200 OK

application/json

[
    {
        "job_id": 0,
        "command": "string",
        "arguments": "string"
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "items": {
        "$ref": "#/components/schemas/JobCommand"
    },
    "type": "array",
    "title": "Response Jobs Add Heartbeat"
}

POST /api/jobs/reschedule

Reschedule Jobs

Description

Reschedule a list of killed or failed jobs.

Body parameters: - job_ids: List of job IDs to reschedule. - reset_jobs: If True, reset the count of reschedules for the jobs.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No
`reset_jobs`	query	boolean	False	No

Request body

application/json

{
    "job_ids": [
        1,
        2,
        3
    ]
}

{
    "job_ids": [
        1
    ]
}

Schema of the request body

{
    "properties": {
        "job_ids": {
            "items": {
                "type": "integer"
            },
            "type": "array",
            "title": "Job Ids"
        }
    },
    "type": "object",
    "required": [
        "job_ids"
    ],
    "title": "Body_jobs_reschedule_jobs"
}

Response 200 OK

application/json

Schema of the response body

{
    "type": "object",
    "additionalProperties": true,
    "title": "Response Jobs Reschedule Jobs"
}

PATCH /api/jobs/metadata

Patch Metadata

Description

Update job metadata such as UserPriority, HeartBeatTime, JobType, etc. The argument are all the attributes/parameters of a job (except the ID).

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No

Request body

application/json

{
    "1": {
        "UserPriority": 2,
        "HeartBeatTime": "2025-11-09 03:01:18.687229+00:00",
        "Status": "Done",
        "Site": "Meyrin"
    },
    "2": {
        "UserPriority": 1,
        "HeartBeatTime": "2025-11-09 03:01:18.687235+00:00",
        "JobType": "AnotherType"
    }
}

Schema of the request body

{
    "additionalProperties": {
        "$ref": "#/components/schemas/JobMetaData"
    },
    "type": "object",
    "title": "Updates"
}

Response 204 No Content

POST /api/jobs/search

Search

Description

Creates a search query to the job database. This search can be based on different parameters, such as jobID, status, owner, etc.

Possibilities - Use search to filter jobs based on various parameters (optional). - Use parameters to specify which job parameters to return (optional). - Use sort to order the results based on specific parameters (optional).

By default, the search will return all jobs the user has access to, and all the fields of the job will be returned.

Input parameters

Parameter	In	Type	Default	Nullable
`OpenIdConnect`	header	string	N/A	No
`page`	query	integer	1	No
`per_page`	query	integer	100	No

Request body

application/json

{
    "search": [
        {
            "parameter": "JobID",
            "operator": "eq",
            "value": "5"
        }
    ]
}

{
    "parameters": [
        "JobID",
        "Status"
    ],
    "search": [
        {
            "parameter": "JobID",
            "operator": "in",
            "values": [
                "6",
                "2",
                "3"
            ]
        }
    ],
    "sort": [
        {
            "parameter": "JobID",
            "direction": "asc"
        }
    ]
}

Schema of the request body

{
    "properties": {
        "parameters": {
            "anyOf": [
                {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                }
            ],
            "title": "Parameters",
            "nullable": true,
            "items": {
                "type": "string"
            },
            "type": "array"
        },
        "search": {
            "items": {
                "anyOf": [
                    {
                        "$ref": "#/components/schemas/ScalarSearchSpec"
                    },
                    {
                        "$ref": "#/components/schemas/VectorSearchSpec"
                    }
                ]
            },
            "type": "array",
            "title": "Search",
            "default": []
        },
        "sort": {
            "items": {
                "$ref": "#/components/schemas/SortSpec"
            },
            "type": "array",
            "title": "Sort",
            "default": []
        },
        "distinct": {
            "type": "boolean",
            "title": "Distinct",
            "default": false
        }
    },
    "type": "object",
    "title": "SearchParams"
}

Response 200 OK

application/json

[
    {
        "JobID": 1,
        "JobGroup": "jobGroup",
        "Owner": "myvo:my_nickname",
        "SubmissionTime": "2023-05-25T07:03:35.602654",
        "LastUpdateTime": "2023-05-25T07:03:35.602652",
        "Status": "RECEIVED",
        "MinorStatus": "Job accepted",
        "ApplicationStatus": "Unknown"
    },
    {
        "JobID": 2,
        "JobGroup": "my_nickname",
        "Owner": "myvo:cburr",
        "SubmissionTime": "2023-05-25T07:03:36.256378",
        "LastUpdateTime": "2023-05-25T07:10:11.974324",
        "Status": "Done",
        "MinorStatus": "Application Exited Successfully",
        "ApplicationStatus": "All events processed"
    }
]

Schema of the response body

{
    "type": "array",
    "items": {
        "type": "object",
        "additionalProperties": true
    },
    "title": "Response Jobs Search"
}

Response 206 Partial Content

application/json

[
    {
        "JobID": 1,
        "JobGroup": "jobGroup",
        "Owner": "myvo:my_nickname",
        "SubmissionTime": "2023-05-25T07:03:35.602654",
        "LastUpdateTime": "2023-05-25T07:03:35.602652",
        "Status": "RECEIVED",
        "MinorStatus": "Job accepted",
        "ApplicationStatus": "Unknown"
    },
    {
        "JobID": 2,
        "JobGroup": "my_nickname",
        "Owner": "myvo:cburr",
        "SubmissionTime": "2023-05-25T07:03:36.256378",
        "LastUpdateTime": "2023-05-25T07:10:11.974324",
        "Status": "Done",
        "MinorStatus": "Application Exited Successfully",
        "ApplicationStatus": "All events processed"
    }
]

Schema of the response body

{
    "type": "array",
    "items": {
        "type": "object",
        "additionalProperties": true
    },
    "title": "Response 206 Jobs Search"
}

Response headers

Name	Description	Schema
`Content-Range`	The range of jobs returned in this response	string

POST /api/jobs/summary

Summary

Description

Group jobs by a specific list of parameters. Returns an array of n-uplets, where each n-uplet contains the values of the grouping parameters and the number of jobs that match those values.

Body parameters: - grouping: List of parameters to group the jobs by. - search: List of search parameters to filter the jobs by (optional).

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No

Request body

application/json

{
    "grouping": [
        "string"
    ],
    "search": [
        null
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "grouping": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Grouping"
        },
        "search": {
            "items": {
                "anyOf": [
                    {
                        "$ref": "#/components/schemas/ScalarSearchSpec"
                    },
                    {
                        "$ref": "#/components/schemas/VectorSearchSpec"
                    }
                ]
            },
            "type": "array",
            "title": "Search",
            "default": []
        }
    },
    "type": "object",
    "required": [
        "grouping"
    ],
    "title": "SummaryParams"
}

Response 200 OK

application/json

[
    {
        "JobID": 1,
        "JobType": "User",
        "JobGroup": "Group_0",
        "Site": "Site_48",
        "JobName": "JobName_1",
        "Owner": "admin",
        "OwnerGroup": "admin",
        "VO": "diracAdmin",
        "SubmissionTime": "2025-07-15T07:15:57",
        "RescheduleTime": "null",
        "LastUpdateTime": "2025-07-15T07:15:57",
        "StartExecTime": "null",
        "HeartBeatTime": "null",
        "EndExecTime": "null",
        "Status": "Received",
        "MinorStatus": "Job accepted",
        "ApplicationStatus": "Unknown",
        "UserPriority": 5,
        "RescheduleCounter": 0,
        "VerifiedFlag": "true",
        "AccountedFlag": "false",
        "count": 1
    },
    {
        "JobID": 2,
        "JobType": "User",
        "JobGroup": "Group_0",
        "Site": "Site_36",
        "JobName": "JobName_2",
        "Owner": "admin",
        "OwnerGroup": "admin",
        "VO": "diracAdmin",
        "SubmissionTime": "2025-07-15T07:15:57",
        "RescheduleTime": "null",
        "LastUpdateTime": "2025-07-15T07:15:57",
        "StartExecTime": "null",
        "HeartBeatTime": "null",
        "EndExecTime": "null",
        "Status": "Received",
        "MinorStatus": "Job accepted",
        "ApplicationStatus": "Unknown",
        "UserPriority": 8,
        "RescheduleCounter": 0,
        "VerifiedFlag": "true",
        "AccountedFlag": "false",
        "count": 1
    }
]

[
    {
        "JobGroup": "Group_0",
        "count": 4000
    },
    {
        "JobGroup": "Group_1",
        "count": 2000
    },
    {
        "JobGroup": "Group_3",
        "count": 1000
    },
    {
        "JobGroup": "Group_4",
        "count": 1000
    },
    {
        "JobGroup": "Group_401",
        "count": 20
    },
    {
        "JobGroup": "Group_402",
        "count": 20
    }
]

Schema of the response body

POST /api/jobs/jdl

Submit Jdl Jobs

Description

Submit a list of jobs in JDL format.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`OpenIdConnect`	header	string	N/A	No

Request body

application/json

[
    "Arguments = \"jobDescription.xml -o LogLevel=INFO\";\nExecutable = \"dirac-jobexec\";\nJobGroup = jobGroup;\nJobName = jobName;\nJobType = User;\nLogLevel = INFO;\nOutputSandbox =\n    {\n        Script1_CodeOutput.log,\n        std.err,\n        std.out\n    };\nPriority = 1;\nSite = ANY;\nStdError = std.err;\nStdOutput = std.out;"
]

[
    "Arguments = \"jobDescription.xml -o LogLevel=INFO"
]

Schema of the request body

{
    "items": {
        "type": "string"
    },
    "type": "array",
    "title": "Job Definitions"
}

Response 200 OK

application/json

[
    {
        "JobID": 0,
        "Status": "string",
        "MinorStatus": "string",
        "TimeStamp": "2022-04-13T15:42:05.901Z"
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "items": {
        "$ref": "#/components/schemas/InsertedJob"
    },
    "type": "array",
    "title": "Response Jobs Submit Jdl Jobs"
}

Schemas

Body_auth_get_oidc_token

Name	Type
`client_id`	string
`code`	string\| null
`code_verifier`	string\| null
`device_code`	string\| null
`grant_type`
`redirect_uri`	string\| null
`refresh_token`	string\| null

Body_auth_revoke_refresh_token_by_refresh_token

Name	Type
`client_id`	string
`token`	string
`token_type_hint`	string\| null

Body_jobs_reschedule_jobs

Name	Type
`job_ids`	Array<integer>

Body_jobs_unassign_bulk_jobs_sandboxes

Name	Type
`job_ids`	Array<integer>

ChecksumAlgorithm

Type: string

GroupInfo

Name	Type
`properties`	Array<string>

HeartbeatData

Name	Type
`AvailableDiskSpace`	number\| null
`CPUConsumed`	number\| null
`LoadAverage`	number\| null
`MemoryUsed`	number\| null
`StandardOutput`	string\| null
`Vsize`	number\| null
`WallClockTime`	number\| null

HTTPValidationError

Name	Type
`detail`	Array<ValidationError>

InitiateDeviceFlowResponse

Name	Type
`device_code`	string
`expires_in`	integer
`user_code`	string
`verification_uri`	string
`verification_uri_complete`	string

InsertedJob

Name	Type
`JobID`	integer
`MinorStatus`	string
`Status`	string
`TimeStamp`	string(date-time)

JobCommand

Name	Type
`arguments`	string\| null
`command`	string
`job_id`	integer

JobMetaData

Name	Type
`AccountedFlag`
`ApplicationStatus`	string\| null
`BatchSystem`	string\| null
`CEQueue`	string\| null
`CPUNormalizationFactor`	integer\| null
`EndExecTime`	string(date-time)\| null
`GridCE`	string\| null
`HeartBeatTime`	string(date-time)\| null
`HostName`	string\| null
`JobGroup`	string\| null
`JobName`	string\| null
`JobStatus`	string\| null
`JobType`	string\| null
`LastUpdateTime`	string(date-time)\| null
`LocalAccount`	string\| null
`Memory(MB)`	integer\| null
`MinorStatus`	string\| null
`ModelName`	string\| null
`NormCPUTime(s)`	integer\| null
`Owner`	string\| null
`OwnerGroup`	string\| null
`PayloadPID`	integer\| null
`Pilot_Reference`	string\| null
`PilotAgent`	string\| null
`RescheduleCounter`	integer\| null
`RescheduleTime`	string(date-time)\| null
`Site`	string\| null
`StartExecTime`	string(date-time)\| null
`Status`	string\| null
`SubmissionTime`	string(date-time)\| null
`timestamp`	string(date-time)\| null
`TotalCPUTime(s)`	integer\| null
`UserPriority`	integer\| null
`VerifiedFlag`	boolean\| null
`VO`	string\| null

JobStatus

Type: string

JobStatusUpdate

Name	Type
`ApplicationStatus`	string\| null
`MinorStatus`	string\| null
`Source`	string
`Status`	JobStatus

Metadata

Name	Type
`virtual_organizations`

OpenIDConfiguration

Name	Type
`authorization_endpoint`	string
`code_challenge_methods_supported`	Array<string>
`device_authorization_endpoint`	string
`grant_types_supported`	Array<string>
`issuer`	string
`jwks_uri`	string
`response_types_supported`	Array<string>
`revocation_endpoint`	string
`scopes_supported`	Array<string>
`token_endpoint`	string
`token_endpoint_auth_methods_supported`	Array<string>
`token_endpoint_auth_signing_alg_values_supported`	Array<string>
`userinfo_endpoint`	string

SandboxDownloadResponse

Name	Type
`expires_in`	integer
`url`	string

SandboxFormat

Type: string

SandboxInfo

Name	Type
`checksum`	string
`checksum_algorithm`	ChecksumAlgorithm
`format`	SandboxFormat
`size`	integer

SandboxUploadResponse

Name	Type
`fields`
`pfn`	string
`url`	string\| null

ScalarSearchOperator

Type: string

ScalarSearchSpec

Name	Type
`operator`	ScalarSearchOperator
`parameter`	string
`value`

SearchParams

Name	Type
`distinct`	boolean
`parameters`	Array<string>
`search`	Array<>
`sort`	Array<SortSpec>

SetJobStatusReturn

Name	Type
`failed`
`success`

SetJobStatusReturnSuccess

Name	Type
`ApplicationStatus`	string\| null
`EndExecTime`	string(date-time)\| null
`HeartBeatTime`	string(date-time)\| null
`LastUpdateTime`	string(date-time)\| null
`MinorStatus`	string\| null
`StartExecTime`	string(date-time)\| null
`Status`	JobStatus

SortDirection

Type: string

SortSpec

Name	Type
`direction`	SortDirection
`parameter`	string

SummaryParams

Name	Type
`grouping`	Array<string>
`search`	Array<>

SupportInfo

Name	Type
`email`	string\| null
`message`	string
`webpage`	string\| null

TokenResponse

Name	Type
`access_token`	string
`expires_in`	integer
`refresh_token`	string\| null
`token_type`	string

UserInfoResponse

Name	Type
`dirac_group`	string
`policies`
`preferred_username`	string
`properties`	Array<string>
`sub`	string
`vo`	string

ValidationError

Name	Type
`loc`	Array<>
`msg`	string
`type`	string

VectorSearchOperator

Type: string

VectorSearchSpec

Name	Type
`operator`	VectorSearchOperator
`parameter`	string
`values`

VOInfo

Name	Type
`default_group`	string
`groups`
`support`	SupportInfo

Security schemes

Name	Type	Scheme	Description
OpenIdConnect	openIdConnect