Build workspace automation with the Yodu public API

Quick answer

Generate a workspace key under Settings → MCP & API, send it as Authorization: Bearer YOUR_YODU_API_KEY, and start with GET https://app.yodu.ai/api/workspace. The live reference at https://app.yodu.ai/api/docs documents 18 public resource paths for workspace context, employees, memory, tasks, channels, approvals, schedules, tools, and runtime visibility. Treat the OpenAPI document as canonical, use separate keys per service, and never depend on private application routes.

The API is a curated operating surface

Yodu is not exposing its entire internal application router. The public API is an allowlist for workflows an external service can perform safely inside one workspace.

That distinction makes the contract easier to reason about. A task-intake service does not also need access to checkout, member administration, credential reads, or runtime repair.

The OpenAPI Initiative specification describes the standard behind the machine-readable contract, and Yodu presents that contract through an interactive Scalar API client. Use the UI to explore, or download the JSON for client generation and validation.

Make the first request

Create a service-specific key and store it in a secret manager. Then:

curl --fail-with-body \
  --header "Authorization: Bearer $YODU_API_KEY" \
  https://app.yodu.ai/api/workspace

The key fixes the workspace and user context. Your service should not accept a free-form organization ID from an untrusted caller and expect Yodu to use it.

Continue with the REST API quickstart and keep the live API reference open for exact schemas.

Map the public resources to real workflows

Workspace and overview

Use /workspace and /workspace/overview for a dashboard, daily briefing, or operational digest. These endpoints provide identity and recent aggregate activity.

Employees

Use /agents to resolve the employee that should own a task or to include employee state in a report.

Memory

Use /memory and /memory/{id} to list, read, create, and update approved company context. A good synchronization service prepares a diff and asks for human review instead of replacing the company profile with every source-system edit.

Tasks

Use /tasks, /tasks/{id}, /tasks/{id}/comments, and /tasks/{id}/move for intake, assignment, collaboration, and lifecycle updates.

Channels

Use the channel message, activity, and mark-read routes when an external service needs the visible work stream around an employee.

Operations

Approvals and schedules expose human gates and recurring work. Runtime health and state provide visibility, not bootstrap or repair controls.

Tools

The tool and catalog routes let a service inspect the current capability surface. Connected-account OAuth and sensitive credential administration remain in the app.

The complete REST endpoint map stays intentionally shorter than the generated schema.

Recipe: controlled task intake

An intake service should:

1. authenticate with its own key
2. list employees and resolve a permitted assignee
3. search existing tasks for a duplicate source identifier
4. normalize the incoming request into a title, summary, priority, and labels
5. create one task
6. persist the returned Yodu task ID in the source system
7. read the task after an ambiguous network failure before retrying

Do not assume every failed response means nothing was created. Application-level idempotency prevents duplicate boards and confusing employee assignments.

Recipe: daily operational digest

Use the overview, tasks, approvals, schedules, and runtime-health resources. Summarize:

• blocked and in-review tasks
• pending approvals
• recurring work that failed or is late
• employee ownership gaps
• runtime or file-sync freshness that needs attention

This workflow should invoke only read operations. The current settings flow creates keys with all three scopes, so isolate the digest behind its own key, never let it invoke write or secret operations, and revoke that client-specific key when the service is retired.

Handle errors like an operator

• Replace a lost or revoked key; do not try to reveal it.
• Treat 401 as an authentication problem and 403 as a scope, membership, or role problem.
• Respect Retry-After on 429 and add exponential backoff with jitter.
• Validate inputs against OpenAPI before sending them.
• Never log bearer headers or response data that contains private company context.
• Do not retry writes blindly.

The errors and troubleshooting guide covers the same checks for REST and MCP clients.

Know when MCP is the better interface

Use REST when a service owns explicit control flow. Use Platform MCP when a human is delegating through Claude Code, Claude Desktop, Cursor, or another compatible client and wants tool discovery.

Both use the same workspace-scoped key model, but they serve different interaction patterns. Read Operate Yodu from Claude Code for the conversational path, or open the developer platform to compare both surfaces.