Appearance
PhD Compute API
The PhD Compute API provides programmatic access to GhostScience scientific tools. All endpoints require authentication and are gated behind the PHD_MODE_ENABLED setting (returns 403 when disabled).
Base path: /api/phd
Authentication
All requests require a Bearer token in the Authorization header:
Authorization: Bearer gst_your_api_keyEndpoints
Execute a Computation
POST /api/phd/computeRun a scientific tool and return structured output with provenance.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
tool_name | string | yes | One of: symbolic_math, numerical_solve, statistical_analysis |
parameters | object | no | Tool-specific parameters (see below) |
session_id | string | no | Link computation to a session for history tracking |
skip_provenance | boolean | no | Skip provenance recording (default false) |
Response
json
{
"computation_id": "550e8400-e29b-41d4-a716-446655440000",
"tool_name": "symbolic_math",
"result": {
"latex": "\\frac{x^3}{3}",
"steps": ["..."],
"code": "...",
"warnings": []
},
"result_hash": "sha256...",
"wall_time_ms": 1234.5,
"cached": false
}Error Response (422)
json
{
"detail": {
"error": "SymPy parse error: ...",
"metadata": {}
}
}Tool Parameters
symbolic_math
| Parameter | Type | Required | Values |
|---|---|---|---|
expression | string | yes | Mathematical expression (any syntax) |
operation | string | yes | solve, integrate, differentiate, simplify, series, limit |
variable | string | no | Variable name (default x) |
assumptions | object | no | SymPy assumptions (e.g., {"positive": true}) |
numerical_solve
| Parameter | Type | Required | Values |
|---|---|---|---|
problem_type | string | yes | ode, linear_system, eigenvalue, root_finding |
equations | string | yes | System of equations |
parameters | object | no | Solver parameters |
method | string | no | Specific solver method |
statistical_analysis
| Parameter | Type | Required | Values |
|---|---|---|---|
analysis_type | string | yes | hypothesis_test, regression, time_series, descriptive |
data | string | no | Input data |
parameters | object | no | Analysis parameters |
Get a Computation
GET /api/phd/compute/{computation_id}Retrieve a stored computation record by ID. Organization-scoped -- only records belonging to the caller's org are returned.
Response: Full provenance record with JSON-parsed fields for tool_parameters, library_versions, physical_constants, rng_seeds, data_lineage, participating_orgs, attestation_signatures, input_lineage_per_org, and result_release_status.
Export a Computation
GET /api/phd/compute/{computation_id}/export?format={format}Export a stored computation to a different format.
Query Parameters
| Parameter | Type | Values |
|---|---|---|
format | string | python (or py), matlab (or m), julia (or jl), latex (or tex), jupyter (or ipynb, notebook), c, dockerfile |
Response: Plain text (text/plain) for most formats, or application/json for Jupyter notebooks.
Errors: 404 if the computation is not found, 400 for unsupported format.
Reproduce a Computation
POST /api/phd/reproduce/{computation_id}Re-execute the stored generated_code in a fresh sandbox and compare result hashes for bitwise verification.
Response
json
{
"computation_id": "550e8400-...",
"matches": true,
"original_result_hash": "sha256...",
"reproduced_result_hash": "sha256...",
"exit_code": 0,
"stderr": "",
"wall_time_ms": 2345.6
}Errors: 404 if not found, 400 if no generated_code is stored, 503 if the sandbox is unavailable.
Session History
GET /api/phd/session/{session_id}/history?limit=50List computation records for a session within the caller's organization.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Max records to return |
Response
json
{
"session_id": "sess-abc",
"computations": [{ "...": "..." }]
}Health Check
GET /api/phd/healthPhD subsystem health: sandbox availability and computation cache status.
Response
json
{
"status": "ok",
"sandbox_available": true,
"cache_connected": true,
"cache_backend": "redis",
"phd_mode_enabled": true
}status is ok when the sandbox is available, degraded otherwise.
Capabilities
GET /api/phd/capabilitiesList available PhD tools with JSON Schema parameter descriptions.
Response
json
{
"tools": [
{
"name": "symbolic_math",
"description": "Symbolic algebra/calculus via SymPy (LaTeX and steps).",
"parameters_schema": {
"type": "object",
"required": ["expression", "operation"],
"properties": {
"expression": { "type": "string" },
"operation": {
"type": "string",
"enum": ["solve", "integrate", "differentiate", "simplify", "series", "limit"]
},
"variable": { "type": "string", "default": "x" },
"assumptions": { "type": "object" }
}
}
}
]
}Related
- GhostScience -- feature overview
- SDK Reference -- Python client library
- Clean Room API -- federated computation endpoints
- Workspace API -- workspace endpoints