Nullgap.dev Docs

API reference

Billing and usage

The plan, credits and usage of the organisation.

Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.

OperationMethod and pathWho may call it
Get billingGET /api/orgs/{org}/billingread
Start the trialPOST /api/orgs/{org}/billing/trialadmin
Add creditsPOST /api/orgs/{org}/billing/creditsconsole only (owner)
Get this month's usageGET /api/orgs/{org}/usageread

#Get billing

GET /api/orgs/{org}/billing

Answers the plan, the seats billed, this month's review allowance and the credit balances with their ledger. Prices are set by the server, as agreed for your workspace.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/billing"

Answer (200, application/json)

A Billing object.

{
  "plan": "trial",
  "trialEndsAt": "2026-11-30T09:30:00.000Z",
  "seatPriceUsd": 0,
  "seatsBilled": 5,
  "reviewsIncluded": 250,
  "reviewsUsed": 61,
  "overage": false,
  "overageReviews": 0,
  "coveredByAgreement": false,
  "automationCredits": 0,
  "pentestCredits": 0,
  "hasPaymentMethod": false,
  "ledger": [
    {
      "id": "cr_1b8d4f0a6c27",
      "kind": "automation",
      "amount": 0,
      "reason": "Fix run",
      "refId": "run_9e3c1a7d5b02",
      "at": "2026-11-16T09:30:00.000Z"
    }
  ]
}

#Start the trial

POST /api/orgs/{org}/billing/trial

Starts the organisation's trial. It needs the services agreement to be accepted in the same request, and can be done once per organisation.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
acceptTermsbooleanyesMust be true: it records that the services agreement was accepted.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"acceptTerms":true}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/billing/trial"

Answer (200, application/json)

A Billing object.

{
  "plan": "trial",
  "trialEndsAt": "2026-11-30T09:30:00.000Z",
  "seatPriceUsd": 0,
  "seatsBilled": 5,
  "reviewsIncluded": 250,
  "reviewsUsed": 61,
  "overage": false,
  "overageReviews": 0,
  "coveredByAgreement": false,
  "automationCredits": 0,
  "pentestCredits": 0,
  "hasPaymentMethod": false,
  "ledger": [
    {
      "id": "cr_1b8d4f0a6c27",
      "kind": "automation",
      "amount": 0,
      "reason": "Fix run",
      "refId": "run_9e3c1a7d5b02",
      "at": "2026-11-16T09:30:00.000Z"
    }
  ]
}

Errors specific to this call

StatusCodeWhen
400terms_requiredacceptTerms is not true.
409trial_usedThe organisation already used its trial or is on a plan.

#Add credits

POST /api/orgs/{org}/billing/credits

Adds credits to one of the two balances. This is a stand-in until a payment provider is connected: it works only on a development server, and answers 501 not_configured everywhere else, including the hosted service. Only an owner signed in to the console can call it.

Who may call it: A signed-in owner in the console. No API key may call it.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
kindstringyesWhich balance to add to: credits for fix runs, or credits for pentests. One of: automation, pentest.
amountnumberyesHow many credits to add. Greater than 0 and at most 100000.

Answer (200, application/json)

A Billing object.

{
  "plan": "trial",
  "trialEndsAt": "2026-11-30T09:30:00.000Z",
  "seatPriceUsd": 0,
  "seatsBilled": 5,
  "reviewsIncluded": 250,
  "reviewsUsed": 61,
  "overage": false,
  "overageReviews": 0,
  "coveredByAgreement": false,
  "automationCredits": 0,
  "pentestCredits": 0,
  "hasPaymentMethod": false,
  "ledger": [
    {
      "id": "cr_1b8d4f0a6c27",
      "kind": "automation",
      "amount": 0,
      "reason": "Fix run",
      "refId": "run_9e3c1a7d5b02",
      "at": "2026-11-16T09:30:00.000Z"
    }
  ]
}

Errors specific to this call

StatusCodeWhen
501not_configuredThe server has no payment provider, which is the case everywhere except a development server.
400bad_requestkind is not automation or pentest, or amount is not a number in range.

#Get this month's usage

GET /api/orgs/{org}/usage

Answers what the organisation has used in the current calendar month (UTC): pull request reviews against the allowance, reviews per author, fix runs and pentests.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/usage"

Answer (200, application/json)

A Usage object.

{
  "periodStart": "2026-11-01T00:00:00.000Z",
  "periodEnd": "2026-12-01T00:00:00.000Z",
  "reviewsIncluded": 250,
  "reviewsUsed": 61,
  "byDeveloper": [
    {
      "login": "dana-okafor",
      "reviews": 14,
      "seat": true
    }
  ],
  "automationRuns": 9,
  "automationCreditsUsed": 0,
  "pentests": 1,
  "toolRuns": 4
}

#Objects

The objects the operations above take and return.

#Billing

The organisation's plan, seats, review allowance and credit balances.

FieldTypeAlways presentDescription
planstringyesThe organisation's plan. One of: none, trial, pro, enterprise.
trialEndsAtstring or nullyesWhen the trial ends. Null when no trial was started.
seatPriceUsdnumberyesThe price of one pull request review seat for a month, as agreed for your workspace.
seatsBilledintegeryesHow many seats are billed now. The People page shows the same number.
reviewsIncludedinteger or nullyesPull request reviews included this month, pooled across all seats: the highest number of seats held this month times the reviews each includes. Null when your agreement covers reviews with no pooled quota.
reviewsUsedintegeryesPull request reviews counted so far this month.
overagebooleanyesTrue when reviews beyond the included number are allowed. The same switch as overage in the settings.
overageReviewsintegeryesReviews this month beyond the included number. Always 0 when your agreement covers reviews.
coveredByAgreementbooleannoTrue when the workspace is billed under an agreement, not per seat or per run: there is no review pool, no extra-review charge and no per-run price.
automationCreditsnumberyesThe balance of credits for fix runs.
pentestCreditsnumberyesThe balance of credits for pentests.
hasPaymentMethodbooleanyesTrue when a payment method is on file.
ledgerarray of CreditEntryyesUp to 100 entries of the credit ledger.

#Usage

What the organisation has used in the current calendar month.

FieldTypeAlways presentDescription
periodStartstringyesThe start of the current calendar month, in UTC.
periodEndstringyesThe start of the next calendar month, in UTC.
reviewsIncludedinteger or nullyesPull request reviews included this month, pooled across all seats. Null when your agreement covers reviews with no pooled quota.
reviewsUsedintegeryesPull request reviews counted so far this month.
byDeveloperarray of objectyesReviews per pull request author, busiest first. Seat holders with no reviews this month are listed with 0.
byDeveloper[].loginstringyesThe pull request author's code-host login, in lower case.
byDeveloper[].reviewsintegeryesReviews counted for this author this month.
byDeveloper[].seatbooleanyesTrue when the member with this code-host login holds a seat. False for bots and people who are not members: only members take a seat.
automationRunsintegeryesFix runs started this month.
automationCreditsUsednumberyesCredits spent on fix runs this month.
pentestsintegeryesPentests started this month.
toolRunsintegeryesScanning tool runs started this month.

#CreditEntry

One line in the credit ledger.

FieldTypeAlways presentDescription
idstringyesThe entry's id.
kindstringyesWhich balance the entry belongs to: credits for fix runs, or credits for pentests. One of: automation, pentest.
amountnumberyesThe change to the balance. Positive is a top-up or refund, negative is spend.
reasonstringyesWhy the balance changed.
refIdstring or nullyesThe run or pentest the entry belongs to, when there is one.
atstringyesWhen it was recorded.

Nullgap documentation