Projects

Create and configure projects, check deploy readiness, run test prompts, and deploy.

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

All 13 endpoints on this page require a Cognito JWT from a signed-in dashboard session. An integration key returns 401 on every one of them — see what an API key can reach.

POST /v1/projects

Create a project.

Auth Cognito JWT member

Before you call it

  • Setting settings or allowedOrigins at creation time requires the admin role.

Path parameters

None.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
name string Required Project name. Required.
description string Optional Free-text description.
allowedOrigins string[] Optional Browser origins allowed to use this project's embed keys. Exact match — see CORS & origins.
settings object Optional Project settings object: retrieval, prompt, lead capture, IP allowlist. Merged over the current values.

Response

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/projects' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/projects

List projects

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/projects' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/projects/{projectId}

Get project

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Reads the resource named in the path; there is nothing else to select.

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.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

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

Update a project's name, allowed origins, prompt, model, and retrieval settings.

Auth Cognito JWT admin

Before you call it

  • allowedOrigins takes at most 50 entries, each https://host[:port] or http://localhost[:port]. No wildcards, no empty strings — see CORS & origins.
  • chatModelArn must be a curated Bedrock model id, and anything other than the default needs the Growth plan or above. GET responses only ever return the public model id.
  • hideOpragBranding needs the Pro plan or above; it removes the footer from the widget.

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
name string Optional Display name.
description string Optional Free-text description.
allowedOrigins string[] Optional Browser origins allowed to use this project's embed keys. Exact match — see CORS & origins.
settings object Optional Project settings object: retrieval, prompt, lead capture, IP allowlist. Merged over the current values.

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/projects/{projectId}' \
  -H 'Authorization: Bearer <Cognito JWT>'
DELETE /v1/projects/{projectId}

Archive project

Auth Cognito JWT admin

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

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/projects/{projectId}' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/projects/{projectId}/overview

Project dashboard summary and setup progress

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Reads the resource named in the path; there is nothing else to select.

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.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/projects/{projectId}/overview' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/projects/{projectId}/deploy-readiness

Pre-deploy checklist and blockers

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Reads the resource named in the path; there is nothing else to select.

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.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/projects/{projectId}/deploy-readiness' \
  -H 'Authorization: Bearer <Cognito JWT>'
PATCH /v1/projects/{projectId}/share

Turn the hosted share link at /p/{shareSlug} on, off, or reconfigure it.

Auth Cognito JWT admin

Before you call it

  • The body must carry at least one of shareEnabled, accessMode, or shareSlug.
  • A slug is 3–48 characters of lowercase letters, numbers, and hyphens. Enabling share without one generates a slug.
  • Disabling share removes the slug lookup, so the old link stops resolving.
  • The response is the sanitized project plus shareUrl (/p/{slug}) while share is enabled.

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
shareEnabled boolean Optional Turn the public share link on or off.
accessMode "private" | "public" Optional private requires a share token; public does not.
shareSlug string Optional Slug in the share URL. Must be unique.

Request

JSON 
{
  "shareEnabled": true,
  "accessMode": "public",
  "shareSlug": "acme-support"
}

Response

200 Success

JSON 
{
  "projectId": "proj_abc123",
  "name": "Support Bot",
  "status": "live",
  "settings": {
    "shareEnabled": true,
    "accessMode": "public",
    "shareSlug": "acme-support"
  },
  "shareUrl": "/p/acme-support"
}

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.
409 That shareSlug is already taken by another project.
429 Rate limited. See rate limits.

curl

Shell 
curl -X PATCH 'https://api.dev.oprag.ai/v1/projects/{projectId}/share' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"shareEnabled": true,"accessMode": "public","shareSlug": "acme-support"}'
GET /v1/projects/{projectId}/test-prompts

List suggested and saved prompt tests

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Neither paginated nor filtered from the query string.

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.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/projects/{projectId}/test-prompts' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/projects/{projectId}/test-prompts

Create a saved prompt test for the project.

Auth Cognito JWT admin

Before you call it

  • Prompt length is capped per project.

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
prompt string Required The question to ask during a test run.
expectedAnswer string Optional What a correct answer should contain.
requiredSources string[] Optional Document titles the answer must cite to pass.

Response

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.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/projects/{projectId}/test-prompts' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/projects/{projectId}/test-runs

Run saved or ad hoc prompt tests using project chat settings

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
testIds string[] Optional Stored test prompt ids to run.
prompts object[] Optional Ad-hoc prompts to run without storing them first.

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/projects/{projectId}/test-runs' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/projects/{projectId}/deploy

Deploy, auto-ingest docs, issue sk_live_* and embed_live_* keys

Auth Cognito JWT admin

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

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

Body parameters

None.Publishes the project's current configuration as it is.

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/projects/{projectId}/deploy' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/projects/{projectId}/integration

Integration info (endpoint, curl)

Auth Cognito JWT admin

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Reads the resource named in the path; there is nothing else to select.

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.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/projects/{projectId}/integration' \
  -H 'Authorization: Bearer <Cognito JWT>'

Ready to ship?

Get started free