API Reference

Base URL: https://api.gwc-corp.com

Authentication

Pass your API key in the Authorization header as a Bearer token. Generate your key in the GWC dashboard under Settings → API Keys.

curl https://api.gwc-corp.com/api/tasks \
  -H "Authorization: Bearer YOUR_API_KEY"

Example: create a task

curl -X POST https://api.gwc-corp.com/api/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Generate report",
    "agent": "my-agent",
    "input": "Analyze Q2 sales data"
  }'

More Examples

List tasks with filters

Use query parameters to filter and paginate your task list. Pass offset to fetch subsequent pages.

curl "https://api.gwc-corp.com/api/tasks?status=RUNNING&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a single task

Fetch a specific task by its ID to check status or retrieve results.

curl https://api.gwc-corp.com/api/tasks/task_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a task

Patch a task to update its status, output, or other fields.

curl -X PATCH https://api.gwc-corp.com/api/tasks/task_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "COMPLETED",
    "output": "Q2 sales up 12% year-over-year"
  }'

Check credit balance

Query your current credit balance and usage.

curl https://api.gwc-corp.com/api/credits/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a subscription

Subscribe to a paid tier. Add "seats" for corporate (min 5) or enterprise (min 100). Returns a Stripe Checkout URL — redirect the user to complete payment.

curl -X POST https://api.gwc-corp.com/api/subscriptions/subscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "standard"
  }'

Tasks

POST/api/tasksCreate a new task.
GET/api/tasksList tasks. Supports ?status=RUNNING&limit=50&offset=0.
GET/api/tasks/:idGet a single task by ID.
PATCH/api/tasks/:idUpdate a task (status, output, actions).
POST/api/tasks/:id/approveApprove a task.
POST/api/tasks/:id/retryRetry a failed task.
GET/api/tasks/:id/reviewGet the review state of a task.

Agents

GET/api/agentsList registered agents.
GET/api/agents/departmentsList agent departments.
GET/api/agents/catalogBrowse the agent catalog.

Marketplace

GET/api/marketplace/servicesBrowse available services.
POST/api/marketplace/ordersPlace an order.
GET/api/marketplace/ordersList your orders.
GET/api/marketplace/orders/:idGet order details.

Credits & Billing

GET/api/credits/balanceGet current usage and balance.
POST/api/credits/topupCreate a top-up checkout session (Stripe).
GET/api/subscriptionsGet current subscription tier.
POST/api/subscriptions/subscribeSubscribe or change tier.
POST/api/subscriptions/cancelCancel subscription.
POST/api/subscriptions/resumeResume cancelled subscription.

Auth

POST/api/auth/sessionExchange Firebase ID token for a GWC session.
POST/api/auth/logoutEnd the current session.
POST/api/auth/refreshRefresh session token.

Request & Response Schemas

Tasks

Task object

id string — Unique task identifier, e.g. task_a1b2c3.
name string — Human-readable task name.
assignedAgent string — Agent assigned to this task (POST accepts agent as an alias).
status string — One of: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED, WAITING_APPROVAL. Defaults to PENDING.
input string — Task input (max 50,000 chars).
output string | null — Task output once completed (max 50,000 chars).
createdAt string (ISO 8601) — Creation timestamp.
updatedAt string (ISO 8601) — Last update timestamp.
Single-task responses are wrapped as { task }; list responses as { tasks, total }.

POST /api/tasks — Request body

name required string
agent string — Agent name from the catalog (alias for assignedAgent).
input string — Task input (max 50,000 chars).
status string — Uppercase enum (see Task object). Defaults to PENDING.
projectId string — Project to attach the task to.
description string — Longer task description.
priority number — 0–10, default 0.
parentTaskId string — Parent task ID (for subtasks).
output string — Initial output, if any.
actions string[] — Action log entries stored in task metadata.

PATCH /api/tasks/:id — Request body

name string — New task name.
description string — New description.
priority number — 0–10.
status string — New task status (uppercase enum).
output string — Updated task output (max 50,000 chars).
logs string — Log lines appended to the task’s existing output.
actions string[] — Appended to the task’s action log.
All fields are optional — only the provided fields are updated. Completed or failed tasks reject updates except a transition to CANCELLED; to re-run a failed task use POST /api/tasks/:id/retry.

Agents

Agent object

name string — Unique agent identifier.
displayName string — Display name.
description string — What the agent does.
department string — Department the agent belongs to.
tier number — Internal agent hierarchy: 1 = Director, 2 = Lead, 3 = Specialist.
tags string[] — Tags describing agent capabilities.
premium boolean — Whether this is a premium agent.
requiredTier string — Minimum subscription tier required (e.g. STANDARD, ADVANCED).
locked boolean — Whether the agent is locked for your subscription tier.
model string — Model backing this agent. On GET /api/agents it is included only for Advanced, Corporate, and Enterprise accounts; GET /api/agents/:name and GET /api/agents/resolve always include it.

GET /api/agents — Query parameters

department string — Filter by department name.
tier number — Include only agents at or below this hierarchy tier (1–3).
search string — Full-text search across name, description, and tags.
page integer — Page number, 1-indexed (default 1).
limit integer — Items per page (default 50, max 200).
Response: { agents, departments, total, page, limit }.

Marketplace

Service object

id string — Unique service identifier.
name string — Display name.
description string — Service description.
category string — Service category.
skillTags string[] — Skill tags supplied by the seller.
packages array — Pricing packages: { name, priceCents, description }. Pricing is per package, in USD cents.
portfolioUrls string[] — Portfolio / sample work URLs.
active boolean — Whether the service is listed.
user object — Nested seller: { id, name, avatarUrl, marketplaceSellerProfile: { grade, avgRating, totalJobs, onTimeRate } }.
createdAt string (ISO 8601) — Listing creation timestamp.

Order object

id string — Unique order identifier.
serviceId string — Purchased service ID.
packageName string — Selected package.
status string — One of: AWAITING_PAYMENT, IN_PROGRESS, DELIVERED, COMPLETED, CANCELLED, DISPUTED.
priceCents integer — Agreed price in USD cents.
requirements string — Buyer’s requirements.
deliverableUrls string[] — Deliverable URLs from the seller.
rating number | null — Buyer’s rating after completion.
reviewText string | null — Buyer’s review.
createdAt string (ISO 8601) — Order creation timestamp.
POST /api/marketplace/orders returns { checkoutUrl, orderId } — redirect the buyer to the Stripe Checkout URL to pay.

Credits & Billing

GET /api/credits/balance — Response

topUpCents integer — Top-up balance in cents (excludes allowance).
totalAvailable integer — Total available in cents (allowance + top-up, minus reserved).
totalLoadedCents integer — Lifetime amount loaded, in cents.
totalSpentCents integer — Lifetime spend, in cents.
hasAllowance boolean — Whether a monthly allowance is active.
allowOverflow boolean — Whether spend overflows to top-up balance when the allowance is depleted.
usageBar object — Allowance usage: used / total / remaining (cents), percent, status (normal | warning | depleted), resetsAt (ISO 8601).
balance object — availableUsd / totalLoadedUsd / totalSpentUsd (USD strings), availableCents / reservedCents (integers).

POST /api/credits/topup — Request body

amountCents required integer — Top-up amount in cents, min 500 ($5), max 100000 ($1,000).
Response: { checkoutUrl, amount } — checkoutUrl is the Stripe Checkout Session URL (redirect the user to complete payment); amount echoes the requested amountCents (in cents, not USD).

GET /api/subscriptions — Response

Returns { subscription, effectiveTier, userTier } — subscription may be null if none exists.
subscription.tier string — One of: BASIC, STANDARD, ADVANCED, CORPORATE, ENTERPRISE.
subscription.status string — One of: ACTIVE, CANCELLED, PAST_DUE, TRIALING.
subscription.currentPeriodEnd string (ISO 8601) — When the current billing period ends. Also: cancelAtPeriodEnd (boolean), downgradeTarget (string | null).
For allowance and balance figures, use GET /api/credits/balance.

Auth

POST /api/auth/session — Request body

idToken required string — Firebase ID token from your auth provider.
Returns: { token } — a JWT valid for 7 days. Use it as the Bearer token on subsequent requests. Decode the JWT to read the expiry (exp claim).

POST /api/auth/refresh — Response

Send your current session token as the Bearer token. Returns { token } — a new JWT valid for 7 days. The old token is accepted even if expired, as long as its signature is valid; requests with a missing or invalid-signature token are rejected (401), and tokens whose account no longer exists are rejected (404).

Error Codes

The API uses standard HTTP status codes. Error responses are wrapped in an envelope: { error: { message, code?, details?, timestamp, path } }. The code field is optional — many errors (e.g. most 401s) carry no code, so key off the HTTP status first and treat error.code as a hint.

StatusCodeMeaning
400VALIDATION_ERRORThe request body is malformed or missing required fields.
401AUTHENTICATION_ERRORMissing or invalid Authorization header. Often returned with no code field.
402STRIPE_ERRORA payment processing error occurred.
403AUTHORIZATION_ERRORYour tier or role does not permit this operation.
404NOT_FOUNDThe requested resource does not exist.
409CONFLICTThe request conflicts with the current state (e.g. resource already exists).
429RATE_LIMITED / RATE_LIMIT_EXCEEDEDToo many requests — see Rate Limiting below. Rate-limiter 429 bodies contain only { error: { message, code } } (no timestamp/path).
500INTERNAL_SERVER_ERROR / DATABASE_ERRORAn unexpected server error occurred. Retry with exponential backoff.

Example error response:

{
  "error": {
    "message": "Task not found",
    "code": "NOT_FOUND",
    "timestamp": "2026-07-05T12:00:00.000Z",
    "path": "/api/tasks/task_abc123"
  }
}

For 429 responses, retry timing comes from the Retry-After and RateLimit-Reset headers, not the response body.

Rate Limiting

Rate limits are applied per API key to ensure fair usage across all tenants. Limits vary by subscription tier.

TierRequests / minuteBurst
basic3050
standard60100
advanced300500
corporate500800
enterprise1,0002,000

AI-specific rate limits

Chat, agents, and media generation endpoints have separate (lower) rate limits per API key:

TierRequests / minuteBurst
basic1525
standard4067
advanced120200
corporate400667
enterprise8001,333

Rate limit headers

Every response includes these headers so you can track your usage:

RateLimit-Limit — Your tier’s cap for the current 60-second window (requests-per-minute plus burst).
RateLimit-Remaining — Requests remaining in the current window.
RateLimit-Reset — Seconds until the current window resets.
A RateLimit-Policy header describing the active policy is also sent.

When you hit the limit

The API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait. We recommend exponential backoff with jitter.

Pagination

Pagination is per-endpoint — there are no cursors.

GET /api/tasks

limit integer — Items per page (default 50, max 100).
offset integer — Number of items to skip (default 0).
Response: { tasks, total }.

GET /api/agents

page integer — Page number, 1-indexed (default 1).
limit integer — Items per page (default 50, max 200).
Response: { agents, departments, total, page, limit }.

GET /api/marketplace/services

page integer — Page number, 1-indexed (default 1).
limit integer — Items per page (default 20, max 50).
Response: { services, total, page, pages }.

Example: paginate tasks with offset

# First page
curl "https://api.gwc-corp.com/api/tasks?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response: { "tasks": [ ... ], "total": 142 }

# Next page
curl "https://api.gwc-corp.com/api/tasks?limit=50&offset=50" \
  -H "Authorization: Bearer YOUR_API_KEY"