Developer Reference

API Reference

FridayOS internal API. All authenticated endpoints require a valid operator session. External integrations use webhooks or the public REST surface.

Authentication: Most endpoints use withSecurity() middleware which validates the session token from the Authorization: Bearer <token> header. Webhook endpoints are intentionally unauthenticated — they verify signatures instead.
🎯

Missions

GET/api/missions🔒 auth

List all missions. Optionally filter by workspace.

Parameters
idstringReturn a single mission by ID
workspacestringFilter missions by workspace ID
Responses
200Array of Mission objects
404Mission not found
POST/api/missions🔒 auth

Create a new mission.

Body
{ title, workspaceId, ownerId, goal?, assignedAgents? }
Responses
201Created Mission object
400Missing required fields
🤖

Agents

GET/api/agent-memory🔒 auth

Read conversation turns for an agent + workspace.

Parameters
agentId*stringAgent ID to fetch memory for
workspaceId*stringWorkspace scope
limitnumberMax turns to return (default 50)
listbooleanSet true to list conversation summaries
Responses
200Array of conversation turns or summaries
GET/api/agent-workspace🔒 auth

Fetch the full workspace view model for an agent: status, transparency feed, confidence.

Parameters
agentId*stringAgent identifier
workspaceId*stringWorkspace identifier
Responses
200AgentWorkspaceViewModel object
POST/api/agent-workspace/actions🔒 auth

Send a named action to the agent workspace (e.g. resume, pause, inject).

Body
{ agentId, workspaceId, action: "resume" | "pause" | "inject" }
Responses
200Action result
400Invalid action
⚙️

Jobs

GET/api/jobs🔒 auth

List all runtime jobs, or fetch one by ID.

Parameters
idstringReturn a single job by ID
Responses
200Array of RuntimeJob objects
404Job not found
POST/api/jobs🔒 auth

Create a new runtime job.

Body
{ title, agentId, workspaceId, summary? }
Responses
201Created RuntimeJob object
📋

Activities & Ledger

GET/api/activities🔒 auth

List activities. Optional single-item lookup by ?id=.

Parameters
idstringReturn a single activity by ID
Responses
200Array of ActivityRecord objects
404Activity not found
POST/api/activities🔒 auth

Record a new activity.

Body
{ title, agentId, workspaceId }
Responses
201Created ActivityRecord object
GET/api/ledger🔒 auth

List ledger items or fetch one by ?id=.

Parameters
idstringReturn a single ledger item by ID
Responses
200Array of LedgerItem objects
404Ledger item not found
POST/api/ledger🔒 auth

Create a new ledger item.

Body
{ title, agentId, workspaceId, detail? }
Responses
201Created LedgerItem object
🗂

Artifacts

GET/api/artifacts🔒 auth

List all runtime artifacts (not studio artifacts).

Responses
200Array of RuntimeArtifact objects
POST/api/artifacts/upload🔒 auth

Upload a file as a runtime artifact. Accepts multipart/form-data.

Body
multipart/form-data: file (required), name?, kind?, agentId?, workspaceId?, summary?
Responses
201Created RuntimeArtifact with url field
400Missing file field
413File too large (max 10 MB)
🎨

Studio

POST/api/studio/dry-run🔒 auth

Simulate artifact generation (mock). Returns a StudioArtifact with 'completed' status.

Body
{ prompt, type: "image"|"video"|"voice"|"code"|"doc", agentId, workspaceId, preferredProviderId? }
Responses
200StudioArtifact object (simulated)
POST/api/studio/generate🔒 auth

Attempt live artifact generation. Falls back to dry-run if gateway unavailable.

Body
{ prompt, type, agentId, workspaceId, preferredProviderId?, size?, quality? }
Responses
200{ success, artifact, stage, latencyMs } — live or dry-run
✅

Reviews

GET/api/reviews🔒 auth

List pending and completed reviews.

Responses
200Array of Review objects
POST/api/reviews🔒 auth

Create a new review request.

Body
{ missionId, artifactId, reviewerId, verdict: "pending"|"approved"|"rejected"|"needs_changes" }
Responses
201Created Review object
🛡️

Governance

POST/api/firewall/evaluate🔒 auth

Evaluate a proposed action against the firewall policy.

Body
{ agentId, workspaceId, action, resource? }
Responses
200{ allowed, reason, tier, tierLabel }
POST/api/approvals🔒 auth

Submit an approval decision for a pending review.

Body
{ reviewId, verdict: "approved"|"rejected"|"needs_changes", reviewerId, reason? }
Responses
201Updated Review object
🐙

Webhooks

GET/api/webhooks/github🌐 no-auth

Health check for the GitHub webhook endpoint.

Responses
200Service info object
POST/api/webhooks/github🌐 no-auth

Receive GitHub webhook events. Verifies HMAC-SHA256 signature if WEBHOOK_SECRET is set.

Parameters
X-GitHub-Event*headerEvent type (push, pull_request, etc.)
X-GitHub-Delivery*headerUnique delivery ID
X-Hub-Signature-256headerHMAC signature (required if WEBHOOK_SECRET is set)
Responses
200{ ok, event, deliveryId, webhookEventId, processed }
401Invalid signature
🔌

Providers

GET/api/provider-status🔒 auth

Health and configuration status of all registered providers.

Responses
200Array of ProviderHealth objects
POST/api/providers/test🔒 auth

Send a test prompt to a provider and return the response.

Body
{ providerId, model?, prompt, stream? }
Responses
200Provider test result
⚡

Runtime

GET/api/runtime-dashboard🔒 auth

Aggregated runtime stats: jobs, activities, artifacts, adapters, runner.

Responses
200RuntimeDashboard object
GET/api/cost-dashboard🔒 auth

Usage events aggregated by workspace, day, and provider.

Parameters
workspaceIdstringFilter by workspace (default fridayos)
daysnumberTime window (default 7, max 30)
Responses
200Cost summary with daily, provider, and agent breakdowns
← Site Map Architecture Docs