Reference

API Reference

The Ribix REST API lets you list, inspect, approve, and reject findings programmatically. All endpoints require a workspace token and return JSON.

Base URL

https://api.ribix.dev/api/v1

Authentication

Pass your workspace token in the Authorization header on every request. You can find your token in the Ribix dashboard under Settings → Workspace → API Token.

curl

curl https://api.ribix.dev/api/v1/findings \
  -H "Authorization: Bearer <workspace-token>"

Keep your token secret.

Workspace tokens grant full read and write access to your findings. Never commit them to source control. Rotate them from the dashboard if they are exposed.

Errors

All errors return a JSON body with a error field and an HTTP status code. Common status codes:

400

Bad Request - Missing or invalid parameters.

401

Unauthorized - Token missing or invalid.

403

Forbidden - Token valid but not authorized for this resource.

404

Not Found - The requested finding does not exist.

429

Too Many Requests - Rate limit exceeded. Retry after the interval in the Retry-After header.

500

Internal Server Error - Something went wrong on our end.

Endpoints

GET/findings

Return a paginated list of findings for the authenticated workspace.

Query parameters

Parameter	Type	Required	Description
severity	string	No	Filter by severity level. One of: p0, p1, p2, p3.
status	string	No	Filter by status. One of: pending, approved, rejected, open.
limit	integer	No	Number of results per page. Default 20, max 100.
offset	integer	No	Number of results to skip. Use with limit for pagination. Default 0.

curl

curl "https://api.ribix.dev/api/v1/findings?severity=p1&status=pending&limit=10" \
  -H "Authorization: Bearer <workspace-token>"

response (200)

{
  "findings": [
    {
      "id": "find_abc123",
      "severity": "p1",
      "status": "pending",
      "title": "TypeError: Cannot read 'total' on checkout",
      "created_at": "2026-06-15T10:23:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

GET/findings/:id

Return a single finding by ID, including the full description, proposed fix diff, and test result.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The finding ID returned by the list endpoint (e.g. find_abc123).

curl

curl https://api.ribix.dev/api/v1/findings/find_abc123 \
  -H "Authorization: Bearer <workspace-token>"

response (200)

{
  "id": "find_abc123",
  "severity": "p1",
  "status": "pending",
  "title": "TypeError: Cannot read 'total' on checkout",
  "description": "The checkout summary renders before the cart totals are resolved...",
  "candidate_files": ["src/components/Checkout/Summary.tsx"],
  "proposed_fix": {
    "diff": "- const total = CartStore.total;
+ const total = CartStore.total ?? 0;",
    "test_result": { "passed": 42, "failed": 0 }
  },
  "created_at": "2026-06-15T10:23:00Z",
  "updated_at": "2026-06-15T10:25:00Z"
}

POST/findings/:id/approve

Approve a finding. Ribix will open a GitHub PR with the failing test and proposed fix.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The finding ID to approve.

No request body is required. The response includes the URL of the created GitHub PR.

curl

curl -X POST https://api.ribix.dev/api/v1/findings/find_abc123/approve \
  -H "Authorization: Bearer <workspace-token>"

response (200)

{
  "id": "find_abc123",
  "status": "approved",
  "pr_url": "https://github.com/your-org/your-repo/pull/42"
}

POST/findings/:id/reject

Reject a finding with an optional reason. The finding is closed and will not produce a PR.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The finding ID to reject.

Request body

Parameter	Type	Required	Description
reason	string	No	Human-readable explanation of why the finding was rejected.

curl

curl -X POST https://api.ribix.dev/api/v1/findings/find_abc123/reject \
  -H "Authorization: Bearer <workspace-token>" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Known limitation, tracked in issue #87."}'

response (200)

{
  "id": "find_abc123",
  "status": "rejected",
  "reason": "Known limitation, tracked in issue #87."
}

Next steps

CLI Reference - approve and reject findings directly from the terminal without the API.
Quick Start - connect your staging environment and run Ribix for the first time.
Integrations - GitHub App setup and staging environment requirements.