Code References

RedPennon discovers where your flag variable keys are referenced in source code from your CI pipeline and surfaces them on each flag's detail page. Your CI scans the working tree (via the RedPennon CLI / GitHub Action) and POSTs a full snapshot of references for one repository and branch to this endpoint. There is no repository OAuth and no server-side scanning.

Plan availability

Code references are available on the Business and Enterprise plans. A token minted on a lower tier is rejected with 402 (see below).

Authentication

These endpoints use an organisation API token (rpa_…), not the environment X-API-Key. See Authentication → Organisation API tokens.

Authorization: Bearer rpa_xxxxxxxxxxxxxxxxxxxxxxxx

Ingest a snapshot

POST /v1/code-references

Records the complete set of references for one repository + branch. The snapshot is authoritative: any reference previously recorded for that repository that is absent from this payload is marked stale (it is not deleted). The repository connection is auto-created on the first push.

Request

POST /v1/code-references HTTP/1.1
Host: api.redpennon.dev
Authorization: Bearer rpa_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "project": "web",
  "provider": "github",
  "repository": "acme/web",
  "branch": "main",
  "commit_sha": "a1b2c3d4",
  "references": [
    {
      "key": "dark-mode",
      "file": "src/theme.ts",
      "line_number": 42,
      "snippet": "client.variable('dark-mode')"
    }
  ]
}

Field	Required	Description
project	yes	Project slug within the organisation. Unknown slug → 404.
provider	no	github (default), gitlab, or bitbucket.
repository	yes	owner/repo.
branch	yes	Branch the snapshot was taken from.
commit_sha	no	Commit the scan ran against; recorded on the connection.
references	yes	List of reference objects. May be empty (marks all existing references stale).
references[].key	yes	The captured variable key.
references[].file	yes	Repository-relative file path.
references[].line_number	no	1-based line of the occurrence.
references[].snippet	no	Short matched snippet for display.

Keys that don't correspond to a variable in the project are accepted but reported back in unknown_keys (matching is pattern-capture, so the CLI does not need a key list).

Response

200 OK

{
  "accepted": 12,
  "matched": 10,
  "unknown_keys": ["legacy-flag", "typo-key"]
}

Field	Description
accepted	Number of reference objects received.
matched	Number that mapped to a known project variable.
unknown_keys	Sorted keys that did not match any variable in the project.

Errors

Status	Condition
400	Invalid JSON, a body that is not a JSON object, missing project/branch, malformed repository, unsupported provider (not github/gitlab/bitbucket), or a malformed references entry.
401	Missing, malformed, unknown, or revoked organisation API token.
402	The organisation's plan does not include code references (server-side gate, beyond the app UI).
403	The organisation is suspended (organisation_suspended) or has no active subscription or trial (organisation_inactive).
404	Unknown project slug.

List project keys (optional)

GET /v1/code-references/keys?project=web

Returns the project's non-deleted variable slugs. Used only by rp usages --only-unused to flag scanned keys that don't exist in the project; not required for ingest.

{ "keys": ["dark-mode", "new-checkout", "show-banner"] }

Same authentication, plan gate (402), and project validation (400/404) as the ingest endpoint.