GODLE API reference

Authorization: Bearer sk-godle-your-key-here

# Comma-separated list of valid keys
wrangler secret put GODLE_API_KEYS
# When prompted, enter: sk-godle-key1,sk-godle-key2

{
  "error": {
    "code":    "RATE_LIMITED",
    "message": "Too many requests. Limit: 60/min"
  }
}

{
  "error": {
    "code":    "ERROR_CODE",
    "message": "Human-readable description"
  }
}

{
  "version":     "3.0.0",
  "generatedAt": "2026-02-25T00:00:00Z",
  "totalRoles":  185,
  "roles": [
    {
      "slug":         "copywriter",
      "name":         "Copywriter",
      "category":     "content",
      "description":  "Expert at persuasive, brand-aligned copy",
      "systemPrompt": "You are an expert copywriter...",
      "templates": [
        {
          "key":    "product-launch-email",
          "label": "Product Launch Email",
          "prompt": "Write a product launch email for..."
        }
      ],
      "nextSteps": ["designer", "strategist"]
    }
  ]
}

{
  "id":              "copywriter--product-launch-email",
  "roleId":          "copywriter",
  "templateKey":     "product-launch-email",
  "templateLabel":   "Product Launch Email",
  "intent":          ["write launch email", "announce product"],
  "tags":            ["email", "marketing", "launch"],
  "domains":         ["saas", "ecommerce", "startup"],
  "outputSections":  ["subject", "preview", "body", "cta"],
  "constraints":     { "estimatedOutputTokens": 800 }
}

curl https://godle.app/api/v3/evals/copywriter--product-launch-email.json

{ "intent": "write a compelling product launch email" }

{
  "intent":          "write a compelling product launch email",
  "totalCandidates": 1741,
  "matches": [
    {
      "capabilityId":  "copywriter--product-launch-email",
      "roleId":        "copywriter",
      "templateKey":   "product-launch-email",
      "score":         4,
      "outputSections": ["subject", "preview", "body", "cta"],
      "constraints":   { "estimatedOutputTokens": 800 }
    }
  ]
}

{
  "capabilityId": "copywriter--product-launch-email",
  "budget":       0.10,
  "latencyMs":    4000,
  "qualityLevel": "high"
}

{
  "config": {
    "defaultTone":        "balanced",
    "maxConcurrentTasks": 5,
    "costBudgetTokens":   100000
  },
  "callerAgent": { "name": "my-agent", "version": "1.0" }
}

{
  "id":        "ses_abc12345",
  "version":   "3.0.0",
  "keyId":     "key_abc12345",
  "createdAt": "2026-02-25T10:00:00Z",
  "expiresAt": "2026-02-25T22:00:00Z",
  "status":    "active",
  "config":    {
    "defaultTone":        "balanced",
    "costBudgetTokens":   100000,
    "costConsumedTokens": 0
  },
  "tasks": []
}

{ "id": "ses_abc12345", "status": "ended" }

{
  "id":          "task_xyz98765",
  "status":      "submitted",
  "roleId":      "copywriter",
  "templateKey": "product-launch-email",
  "createdAt":   "2026-02-25T10:00:00Z"
}

{
  "id":          "task_xyz98765",
  "status":      "completed",
  "completedAt": "2026-02-25T10:00:42Z",
  "artifacts": [
    {
      "id":         "art_abc12345",
      "type":       "text",
      "mimeType":   "text/plain",
      "content":    "Subject: Something big is coming...",
      "evalResult": { "passed": true, "score": 92, "checks": [] },
      "provenance": {
        "modelUsed":    "claude-sonnet-4-6",
        "generatedAt": "2026-02-25T10:00:42Z",
        "attempt":     1
      }
    }
  ],
  "runLog": {
    "totalAttempts": 1,
    "model":         "claude-sonnet-4-6",
    "usage":         { "input_tokens": 512, "output_tokens": 280, "total_tokens": 792 },
    "evalScore":     92,
    "evalPassed":    true
  }
}

{ "approved": true, "reason": "Looks good, proceed" }

const res = await fetch(`/api/v3/tasks/${taskId}/stream`, {
  headers: { 'Authorization': 'Bearer sk-godle-your-key' }
});

const reader  = res.body.getReader();
const decoder = new TextDecoder();
let buf = '';
let currentEvent = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buf += decoder.decode(value, { stream: true });
  const lines = buf.split('\n');
  buf = lines.pop(); // keep the incomplete trailing line

  for (const line of lines) {
    if (line.startsWith('event: ')) {
      currentEvent = line.slice(7).trim();
      continue;
    }
    if (!line.startsWith('data: ')) continue;

    const data = JSON.parse(line.slice(6));

    if (currentEvent === 'partial_artifact') {
      renderPreview(data.preview); // stream preview to UI
    }
    if (currentEvent === 'complete') {
      console.log(data.artifacts[0].content);
      reader.cancel();
    }
    if (currentEvent === 'error') {
      console.error(data.error);
      reader.cancel();
    }
  }
}

{
  "workflow": {
    "id": "launch-campaign",
    "steps": [
      {
        "id":     "research",
        "roleId": "researcher",
        "input":  "Top SaaS growth strategies 2025"
      },
      {
        "id":        "copy",
        "roleId":    "copywriter",
        "prompt":    "Write a launch email using these insights: {{steps.research.output}}",
        "dependsOn": ["research"],
        "modelHint": "balanced"
      }
    ]
  },
  "inputs":      { "audience": "remote teams" },
  "autoApprove": true
}

{
  "jsonrpc": "2.0",
  "id":      1,
  "method":  "tools/call",
  "params":  {
    "name":      "godle/execute_task",
    "arguments": {
      "roleId": "copywriter",
      "input":  "Write a tagline for a coffee brand"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id":      1,
  "result":  {
    "content":    [{ "type": "text", "text": "Wake up, world." }],
    "taskId":     "task_xyz",
    "evalResult": { "passed": true, "score": 95 }
  }
}

{
  "method":  "tasks/send",
  "id":      "my-task-123",
  "message": {
    "role":  "user",
    "parts": [{ "type": "text", "text": "Write a product tagline for a coffee brand" }]
  },
  "skill": { "roleId": "copywriter" }
}

{
  "id":        "my-task-123",
  "status":    { "state": "completed" },
  "artifacts": [{
    "index": 0,
    "name":  "output",
    "parts": [{ "text": "Wake up, world." }]
  }],
  "metadata": { "godleTaskId": "task_xyz98765" }
}

<script src="https://godle.app/api/v3/godle-sdk.js"></script>

const result = await GODLE.run('copywriter', 'Write a tagline for a coffee brand', {
  tone:  'friendly',
  model: 'claude-sonnet-4-6'
});

console.log(result.output);           // "Wake up, world."
console.log(result.evalResult.score); // 0–100

const suggestions = await GODLE.suggest('I need a compelling product launch email');
// Returns ranked role + template matches

const wf = GODLE.buildWorkflow('launch-campaign')
  .step('research', 'researcher', 'Top SaaS strategies 2025')
  .step('copy', 'copywriter', '{{steps.research.output}}', { dependsOn: ['research'] })
  .build();

const result = await GODLE.run(wf);

const session = await GODLE.createSession({
  baseUrl: 'https://orchestration.godle.app',
  apiKey:  'sk-godle-your-key',
  config:  { costBudgetTokens: 50000 }
});

// session.id is a server-side ID, e.g. "ses_abc12345"
const result = await GODLE.run('copywriter', 'Write a tagline', { session });

const stream = await GODLE.connectStream(taskId, {
  baseUrl:    'https://orchestration.godle.app',
  apiKey:     'sk-godle-your-key',
  onProgress: msg  => console.log('progress:', msg),
  onComplete: task => console.log(task.artifacts[0].content)
});

const mcp = GODLE.mcp.client({ baseUrl: 'https://orchestration.godle.app', apiKey: 'sk-godle-...' });

const roles  = await mcp.listRoles({ limit: 10 });
const result = await mcp.executeTask({ roleId: 'copywriter', input: 'Write a tagline' });

const a2a = GODLE.a2a.client({ baseUrl: 'https://orchestration.godle.app' });

const task    = await a2a.send({
  message: GODLE.a2a.makeMessage('Write a product tagline for a coffee brand'),
  skill:   { roleId: 'copywriter' }
});

const a2aTask = GODLE.a2a.toA2ATask(task);
console.log(a2aTask.artifacts[0].parts[0].text);

const adapter = GODLE.adapters.anthropic({ apiKey: 'sk-ant-...' });
// or
const adapter = GODLE.adapters.openai({ apiKey: 'sk-...' });

const result = await GODLE.run('copywriter', 'Write a tagline', { adapter });

# 1. Create the KV namespace for rate limiting
wrangler kv:namespace create RATE_LIMITS
# → copy the returned id into wrangler.toml

# 2. Set secrets
wrangler secret put GODLE_API_KEYS     # sk-godle-key1,sk-godle-key2
wrangler secret put ANTHROPIC_API_KEY  # sk-ant-...
wrangler secret put OPENAI_API_KEY     # sk-...  (optional)

# 3. Deploy
wrangler deploy