OpenGray Workspace SDK

Version 1 · Last updated November 8, 2026

OpenGray provides an interactive browser Playground alongside a standard REST interface for automating prompt evaluations, structured JSON output assertions, and telemetry logging from your CI/CD pipelines.

Authentication

Every request must carry a scoped project token issued from your workspace dashboard. Tokens are shown once at creation and stored only as a SHA-256 hash, so keep a copy in your CI secret manager. A token can be revoked at any time and can carry an optional environment quota cap.

Quickstart

Create a workspace account, activate a plan, then trigger your first evaluation run:

curl https://open-gray.com/api/v1/evaluations/run \
  -H "Authorization: Bearer sk-og-v1-..." \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "og-reasoning-pro",
    "suite": "q3-revenue-summary",
    "input": "Summarise our Q3 revenue drivers."
  }'

import requests

response = requests.post(
    "https://open-gray.com/api/v1/evaluations/run",
    headers={"Authorization": "Bearer sk-og-v1-..."},
    json={
        "engine": "og-reasoning-pro",
        "suite": "q3-revenue-summary",
        "input": "Summarise our Q3 revenue drivers.",
    },
)

print(response.json()["output"])

const response = await fetch("https://open-gray.com/api/v1/evaluations/run", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-og-v1-...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    engine: "og-reasoning-pro",
    suite: "q3-revenue-summary",
    input: "Summarise our Q3 revenue drivers.",
  }),
});

const result = await response.json();
console.log(result.output);

<?php
$payload = [
    'engine' => 'og-reasoning-pro',
    'suite'  => 'q3-revenue-summary',
    'input'  => 'Summarise our Q3 revenue drivers.',
];

$ch = curl_init('https://open-gray.com/api/v1/evaluations/run');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer sk-og-v1-...',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);

$body = json_decode(curl_exec($ch), true);
echo $body['output'];

Run evaluation

POST /evaluations/run

Request fields:

A successful evaluation response returns the validated output and workspace telemetry:

{
  "id": "eval-1a2b3c",
  "object": "workspace.evaluation",
  "created": 1785794208,
  "engine": "og-reasoning-pro",
  "output": "...",
  "status": "completed",
  "telemetry": {
    "prompt_tokens": 412,
    "completion_tokens": 180,
    "total_tokens": 592,
    "latency_ms": 640
  }
}

Streaming telemetry

Set "stream": true to receive text/event-stream frames. Each frame is a data: line containing a chunk object, and the stream terminates with data: [DONE].

curl -N https://open-gray.com/api/v1/evaluations/run \
  -H "Authorization: Bearer sk-og-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"engine":"og-reasoning-pro","stream":true,"input":"Verify JSON schema compliance."}'

List suites

GET /models returns the active workspace evaluation profiles and their context specifications.

{
  "object": "list",
  "data": [
    {
      "id": "og-reasoning-pro",
      "object": "suite",
      "owned_by": "OpenGray Workspace",
      "context_length": 1000000
    }
  ]
}

Workspace status

GET /key returns the calling project token's metadata and remaining plan allocation. Use it for preflight checks in CI pipelines.

{
  "data": {
    "label": "Staging CI",
    "plan": "Pro",
    "remaining_units": 4120,
    "status": "active"
  }
}

Plan quotas

• Each workspace plan (Starter, Pro, Team, Scale) includes a fixed allocation of evaluation units.
• Repeated prompt prefixes in test suites benefit from automatic regression caching.
• Runs pause cleanly with HTTP 402 when your plan quota is reached, preventing unexpected overage charges.
• Every evaluation run is logged on the activity page with latency and schema status.

Errors

Errors use a standard JSON envelope: {"error": {"message": "...", "type": "...", "code": 400}}.

Limits

• Payload limit: 8 MB per evaluation run.
• Synchronous timeout: 300 seconds. Streaming timeout: 600 seconds.
• Scoped project tokens per workspace: up to 5 on Starter, unlimited on Pro, Team, and Scale.

CI/CD integration

Standard HTTP & Webhooks: configure your test runner to call https://open-gray.com/api/v1/evaluations/run, authenticate with your scoped workspace token, and specify your target evaluation profile slug (such as og-reasoning-pro).

Anything unclear? Write to contact@open-gray.com and our engineering team will help.