Workspace

Workspace settings, members, analytics, and billing. The API calls a workspace a `company`.

dev · https://api.dev.oprag.ai

18 endpoints. 1 are reachable without a dashboard session — they are listed in the Integration API — and the other 17 require a Cognito JWT. The badge under each path says which.

GET /v1/dashboard/summary

Dashboard KPIs and project rollups

Auth Cognito JWT member

Path parameters

None.

Query parameters

None.Scoped by the calling credential, so there is nothing in the URL to narrow.

Body parameters

None.GET requests carry no body.

Response

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/dashboard/summary' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/activity

Recent activity across the workspace, newest first.

Auth Cognito JWT member

Before you call it

  • The response is { events, nextCursor }, newest first. nextCursor is null on the last page.

Path parameters

None.

Query parameters

Name Type Required Default Description
cursor string Optional — Opaque cursor from the previous response's nextCursor. Omit for the first page — see pagination. Encodes an offset into the feed.
limit number Optional 20 Events per page. Values above 100 are clamped to 100; a non-numeric or non-positive value falls back to 20.

Body parameters

None.GET requests carry no body.

Response

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/activity' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/analytics/summary

Usage analytics for a date range, with the weak answers worth looking at.

Auth Cognito JWT member

Before you call it

  • coverageGaps lists up to 20 weak-answer signals from recent conversations, each with a reason of bad_rating, no_sources, or both.

Path parameters

None.

Query parameters

Name Type Required Default Description
projectId string Optional — Narrow the result to one project. A project id the workspace does not own is a 404.
from string (ISO 8601) Optional 7 days ago Start of the window, compared against each conversation's createdAt.
to string (ISO 8601) Optional now End of the window, inclusive.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "range": { "from": "2026-06-24T00:00:00.000Z", "to": "2026-07-01T00:00:00.000Z" },
  "totals": {
    "conversations": 42,
    "messages": 128,
    "apiCalls": 35,
    "apiErrors": 0,
    "unresolved": 3,
    "weakAnswers": 2,
    "visitorThumbsUp": 18,
    "visitorThumbsDown": 4
  },
  "series": [
    { "date": "2026-06-25", "conversations": 8, "apiCalls": 5, "apiErrors": 0 }
  ],
  "topSources": [{ "filename": "pricing.pdf", "count": 12 }],
  "coverageGaps": [
    {
      "question": "Do you ship internationally?",
      "reason": "no_sources",
      "projectId": "proj_abc123",
      "conversationId": "conv_xyz789",
      "timestamp": "2026-06-30T14:22:00.000Z"
    }
  ]
}

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/analytics/summary' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/analytics/export

The same analytics as the summary, as a CSV download.

Auth Cognito JWT member

Before you call it

  • The body is text/csv in two sections: the daily series (date, conversations, apiCalls), then the coverage gaps (question, reason, projectId, conversationId, timestamp).
  • The date window and project filter behave exactly as they do on GET /v1/analytics/summary.

Path parameters

None.

Query parameters

Name Type Required Default Description
projectId string Optional — Narrow the export to one project. A project id the workspace does not own is a 404.
from string (ISO 8601) Optional 7 days ago Start of the window, compared against each conversation's createdAt.
to string (ISO 8601) Optional now End of the window, inclusive.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
date,conversations,apiCalls
2026-06-25,8,5
2026-06-26,12,7

question,reason,projectId,conversationId,timestamp
Do you ship internationally?,no_sources,proj_abc123,conv_xyz789,2026-06-30T14:22:00.000Z

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/analytics/export' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/billing/summary

The workspace's plan, its limits, and usage against them.

Auth Cognito JWT member

Before you call it

  • plan is free, growth, pro, or enterprise, and the limits match PLAN_LIMITS in the shared contract: Free 1 project and 500 replies, Growth 2 and 3,000, Pro 5 and 20,000.
  • Leads are unlimited on every plan, so no lead count appears here.
  • No Stripe customer or subscription ids are ever returned.

Path parameters

None.

Query parameters

None.Scoped by the calling credential, so there is nothing in the URL to narrow.

Body parameters

None.GET requests carry no body.

Responses

200 Success

JSON 
{
  "plan": "free",
  "billingStatus": "active",
  "limits": {
    "projects": 1,
    "seats": 2,
    "messagesPerMonth": 500,
    "storageMb": 512
  },
  "usage": {
    "projects": 1,
    "seats": 2,
    "messagesThisMonth": 42,
    "storageMb": 18.5
  },
  "currentPeriod": {
    "startedAt": "2026-07-01T00:00:00.000Z",
    "endsAt": "2026-08-01T00:00:00.000Z"
  }
}

200 Another example

JSON 
{
  "plan": "growth",
  "billingStatus": "active",
  "limits": {
    "projects": 2,
    "seats": 3,
    "messagesPerMonth": 3000,
    "storageMb": 2048
  },
  "usage": {
    "projects": 2,
    "seats": 2,
    "messagesThisMonth": 812,
    "storageMb": 640
  },
  "currentPeriod": {
    "startedAt": "2026-07-01T00:00:00.000Z",
    "endsAt": "2026-08-01T00:00:00.000Z"
  }
}

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/billing/summary' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/billing/invoices

List Stripe invoices for the workspace

Auth Cognito JWT member

Path parameters

None.

Query parameters

None.Scoped by the calling credential, so there is nothing in the URL to narrow.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "invoices": [
    {
      "invoiceId": "INV-1042",
      "date": "2026-06-01",
      "amountCents": 9900,
      "currency": "USD",
      "status": "paid",
      "downloadUrl": "https://..."
    }
  ]
}

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/billing/invoices' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/billing/checkout-session

Start a Stripe checkout session to move the workspace onto a paid plan.

Auth Cognito JWT admin

Before you call it

  • plan must be growth, pro, or enterprise — the Starter, Growth, and Pro tiers on the pricing page.
  • returnUrl is required and must sit under https://app.oprag.ai, https://app.dev.oprag.ai, https://app.stg.oprag.ai, http://localhost, or http://127.0.0.1. Any path under those is accepted.

Path parameters

None.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
plan string Required growth, pro, or enterprise.
returnUrl string Required Where the billing provider sends the customer back to.

Request

JSON 
{
  "plan": "growth",
  "returnUrl": "https://app.oprag.ai/billing"
}

Response

200 Success

JSON 
{
  "checkoutUrl": "https://checkout.stripe.com/..."
}

Status codes

Status Meaning
200 Success.
400 plan is not a paid plan, or returnUrl is not an allowed host.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.
503 Stripe, or the price id for the requested plan, is not configured.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/billing/checkout-session' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"plan": "growth","returnUrl": "https://app.oprag.ai/billing"}'
POST /v1/billing/webhook

Updates the workspace's plan and billing status from Stripe's checkout and subscription events.

Auth Integration key

Before you call it

  • Stripe calls this, not your code. It needs a Stripe-Signature header and the raw, unparsed request body.

Path parameters

None.

Query parameters

None.The provider signs and posts the whole payload; nothing is read from the URL.

Body parameters

Defined by the caller.Signed event envelope from the billing provider. Shape is theirs, not ours.

Response

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing, revoked, or wrong-environment key.
403 Origin or IP not allowed for this project.
429 Rate limited. See rate limits.
503 Stripe is not configured in this environment.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/billing/webhook' \
  -H 'X-Oprag-Key: sk_live_...'
POST /v1/companies

Create the workspace during signup.

Auth Cognito JWT

Before you call it

  • Requires a JWT that has no workspace assigned yet.
  • The response is a CompanyApi — it carries no stripeCustomerId or stripeSubscriptionId.

Path parameters

None.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
name string Required Workspace name.

Request

JSON 
{ "name": "Acme Corp" }

Response

200 Success

JSON 
{
  "companyId": "co_abc123",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "plan": "free",
  "status": "active",
  "ownerUserId": "user_xyz789",
  "createdAt": "2026-06-01T12:00:00.000Z",
  "updatedAt": "2026-06-01T12:00:00.000Z"
}

Status codes

Status Meaning
201 Created.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/companies' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Acme Corp" }'
GET /v1/companies/me

Current workspace profile (CompanyApi — client-safe fields only)

Auth Cognito JWT member

Path parameters

None.

Query parameters

None.Scoped by the calling credential, so there is nothing in the URL to narrow.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "companyId": "co_abc123",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "plan": "free",
  "status": "active",
  "ownerUserId": "user_xyz789",
  "createdAt": "2026-06-01T12:00:00.000Z",
  "updatedAt": "2026-06-01T12:00:00.000Z"
}

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/companies/me' \
  -H 'Authorization: Bearer <Cognito JWT>'
PATCH /v1/companies/me

Update workspace name. Returns CompanyApi.

Auth Cognito JWT admin

Path parameters

None.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
name string Required Workspace name.

Request

JSON 
{ "name": "Acme Corporation" }

Response

200 Success

JSON 
{
  "companyId": "co_abc123",
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "plan": "free",
  "status": "active",
  "ownerUserId": "user_xyz789",
  "createdAt": "2026-06-01T12:00:00.000Z",
  "updatedAt": "2026-06-30T09:00:00.000Z"
}

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X PATCH 'https://api.dev.oprag.ai/v1/companies/me' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Acme Corporation" }'
GET /v1/companies/users

List team members

Auth Cognito JWT member

Path parameters

None.

Query parameters

None.Scoped by the calling credential, so there is nothing in the URL to narrow.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "users": [
    {
      "companyId": "co_abc123",
      "userId": "user_xyz789",
      "email": "owner@acme.com",
      "role": "owner",
      "status": "active",
      "joinedAt": "2026-06-01T12:00:00.000Z",
      "createdAt": "2026-06-01T12:00:00.000Z",
      "updatedAt": "2026-06-01T12:00:00.000Z"
    }
  ]
}

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/companies/users' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/companies/users/invite

Invite a user to the workspace.

Auth Cognito JWT admin

Path parameters

None.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
email string Required Address to send the invitation to.
role string Optional Role to grant on acceptance. Defaults to member.

Request

JSON 
{ "email": "alice@acme.com", "role": "member" }

Response

200 Success

JSON 
{ "userId": "user_inv123", "email": "alice@acme.com", "role": "member", "status": "invited" }

Status codes

Status Meaning
201 Created. The body carries the invited member record.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/companies/users/invite' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{ "email": "alice@acme.com", "role": "member" }'
POST /v1/companies/users/{userId}/resend-invite

Resend invite email

Auth Cognito JWT admin

Path parameters

Name Type Required Description
userId string Required Workspace member.

Query parameters

None.Acts on the resource named in the path; there is nothing to choose.

Body parameters

None.Re-sends the existing invitation; the user is identified by the path.

Response

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/companies/users/{userId}/resend-invite' \
  -H 'Authorization: Bearer <Cognito JWT>'
PATCH /v1/companies/users/{userId}

Change member role

Auth Cognito JWT admin

Path parameters

Name Type Required Description
userId string Required Workspace member.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
role string Required New role for this member.

Response

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X PATCH 'https://api.dev.oprag.ai/v1/companies/users/{userId}' \
  -H 'Authorization: Bearer <Cognito JWT>'
DELETE /v1/companies/users/{userId}

Remove member

Auth Cognito JWT admin

Path parameters

Name Type Required Description
userId string Required Workspace member.

Query parameters

None.Acts on the resource named in the path; there is nothing to choose.

Body parameters

None.DELETE requests carry no body.

Response

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X DELETE 'https://api.dev.oprag.ai/v1/companies/users/{userId}' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/companies/settings

Workspace defaults (origins, prompts, retention)

Auth Cognito JWT member

Path parameters

None.

Query parameters

None.Scoped by the calling credential, so there is nothing in the URL to narrow.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "companyId": "co_abc123",
  "allowedOriginDefaults": ["https://app.acme.com"],
  "defaultChatModelArn": null,
  "defaultSystemPrompt": "You are a helpful assistant.",
  "defaultMaxTokens": 1024,
  "retentionDays": 90,
  "createdAt": "2026-06-01T12:00:00.000Z",
  "updatedAt": "2026-06-01T12:00:00.000Z"
}

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/companies/settings' \
  -H 'Authorization: Bearer <Cognito JWT>'
PATCH /v1/companies/settings

Update workspace defaults

Auth Cognito JWT admin

Path parameters

None.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
allowedOriginDefaults string[] Optional Origins new projects start with.
defaultChatModelArn string | null Optional Model new projects use. null restores the platform default.
defaultSystemPrompt string Optional System prompt new projects start with.
defaultMaxTokens number Optional Answer length ceiling for new projects.
retentionDays number Optional How long conversations are kept.

Response

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X PATCH 'https://api.dev.oprag.ai/v1/companies/settings' \
  -H 'Authorization: Bearer <Cognito JWT>'

Ready to ship?

Get started free