API reference — IssueProbe

Base URL

https://issueprobe.com

Create a Free account

Agent enrollment

GET

`/agent-enrollment/authorize`

Review one agent request

Shows the requested account name, agent name, and exact scopes without an owner email or exchange secret.

Authentication: Owner authorization claim
Idempotency: Safe read. The page does not record a decision.

Responses

Status	Description
`200`	The owner review form.
`401`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

"<!doctype html><title>Authorize an agent</title>"

POST

`/agent-enrollment/authorize`

Approve or reject one agent request

Records one explicit owner decision. Rejection for a new owner email creates no account.

Authentication: Owner authorization claim
Idempotency: The one-use owner claim can record one decision. A repeated POST fails safely.

Parameters

MutationProof

Request example

{
  "decision": "approve",
  "csrfToken": "csrf-example"
}

Responses

Status	Description
`200`	A safe new-owner rejection confirmation.
`303`	An existing owner continues to the credential page.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

"<!doctype html><title>Agent request rejected</title>"

POST

`/v1/agent-enrollments`

Request owner authorization for one agent

Creates one owner-authorized enrollment. Email, client, and one-hundred-email global limits use one fixed hour. An exact valid retry can recover the same unused exchange secret and sends no second email.

Authentication: Public
Idempotency: Requires Idempotency-Key. The same client, key, and request replay one enrollment before rate consumption. A changed request with the same key fails.

Parameters

IdempotencyKey
PublicClient

Request example

{
  "ownerEmail": "[email protected]",
  "accountName": "Example account",
  "agentName": "website-setup-agent",
  "scopes": [
    "websites:write",
    "websites:read",
    "reports:read",
    "reports:write"
  ]
}

Responses

Status	Description
`200`	The exact retry result.
`201`	The pending enrollment and its exchange secret.
`400`	The service returns a stable error code and a safe message.
`409`	The service returns a stable error code and a safe message.
`429`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "enrollmentId": "enr_example",
  "exchangeSecret": "ip_enroll_exchange_example",
  "expiresAt": "2026-08-30T12:00:00Z",
  "replayed": true
}

GET

`/v1/agent-enrollments/authorize`

Start scanner-safe owner authorization

Stores a short-lived owner claim and redirects to the clean review page. The GET does not approve or reject the request.

Authentication: Public
Idempotency: The GET does not consume the owner authorization token.

Parameters

OwnerAuthorizationToken

Responses

Status	Description
`303`	Continue to the clean owner review page.
`400`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

POST

`/v1/agent-enrollments/{enrollmentId}/exchange`

Exchange one approved enrollment secret

Returns one scoped API credential once after owner approval. The exchange and enrollment expire after seven days.

Authentication: Public
Idempotency: The exchange succeeds once. A repeated exchange creates no second credential.

Parameters

EnrollmentId

Request example

{
  "exchangeSecret": "ip_enroll_exchange_example"
}

Responses

Status	Description
`201`	The one-time API credential.
`401`	The service returns a stable error code and a safe message.
`409`	The service returns a stable error code and a safe message.
`410`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "credential": {
    "id": "cred_example",
    "name": "website-setup-agent",
    "token": "ip_api_example",
    "scopes": [
      "websites:write",
      "websites:read"
    ],
    "expiresAt": "2026-11-28T12:00:00Z"
  }
}

Service

GET

`/healthz`

Read process health

Returns process health without an external service call.

Authentication: Public
Idempotency: Safe read. Repeated requests do not change state.

Responses

Status	Description
`200`	The service process is available.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "status": "ok"
}

GET

`/readyz`

Read service readiness

Returns one public readiness state without component names. The service shares concurrent checks and reuses each result for at most five seconds while the HTTP response remains no-store.

Authentication: Public
Idempotency: Safe read. Repeated requests do not change state.

Responses

Status	Description
`200`	The service is ready.
`503`	The service is not ready.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "status": "ready"
}

GET

`/version`

Read the public version

Returns the public application version.

Authentication: Public
Idempotency: Safe read. Repeated requests do not change state.

Responses

Status	Description
`200`	The public version.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "version": "0.1.0"
}

Documentation

GET

`/openapi.json`

Download the OpenAPI document

Returns this customer API contract as OpenAPI 3.1 JSON.

Authentication: Public
Idempotency: Safe read. Repeated requests do not change state.

Responses

Status	Description
`200`	The OpenAPI document.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "openapi": "3.1.0",
  "info": {
    "title": "IssueProbe API",
    "version": "0.1.0"
  },
  "paths": {}
}

API credentials

GET

`/v1/api-credentials`

List API credentials without raw values

Returns safe credential metadata for a human owner.

Authentication: Human owner cookie
Idempotency: Safe read. Repeated requests do not change state.

Responses

Status	Description
`200`	Safe credential metadata.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "items": [
    {
      "id": "cred_example",
      "name": "website-setup-agent",
      "scopes": [
        "websites:read"
      ],
      "createdAt": "2026-08-22T12:00:00Z",
      "expiresAt": "2026-11-20T12:00:00Z",
      "lastUsedAt": null,
      "revokedAt": null
    }
  ]
}

POST

`/v1/api-credentials`

Create one owner-authorized API credential

Only a human owner can create a credential. The raw value appears in this no-store response only.

Authentication: Human owner cookie
Idempotency: This operation does not accept an idempotency key. A successful request creates one new credential.

Parameters

MutationProof

Request example

{
  "name": "website-setup-agent",
  "scopes": [
    "websites:read",
    "reports:read"
  ],
  "expiresAt": "2026-11-20T12:00:00Z"
}

Responses

Status	Description
`201`	The one-time credential response.
`400`	The service returns a stable error code and a safe message.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "credential": {
    "id": "cred_example",
    "name": "website-setup-agent",
    "token": "ip_api_example",
    "scopes": [
      "websites:read",
      "reports:read"
    ],
    "expiresAt": "2026-11-20T12:00:00Z"
  }
}

DELETE

`/v1/api-credentials/{credentialId}`

Revoke one API credential

Only a human owner can revoke a credential. A revoked credential cannot authenticate later calls.

Authentication: Human owner cookie
Idempotency: Repeated revocation requests keep the credential revoked.

Parameters

CredentialId
MutationProof

Responses

Status	Description
`204`	The credential is revoked.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Account

GET

`/v1/audit-events`

List customer-safe account activity

Returns safe human, agent, website, report, credential, enrollment, plan, and subscription actions.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Responses

Status	Description
`200`	Customer-safe account activity.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "items": [
    {
      "actorType": "agent",
      "actorLabel": "website-setup-agent",
      "action": "website.created",
      "createdAt": "2026-08-22T12:00:00Z"
    }
  ]
}

Authentication

GET

`/v1/auth/callback`

Open the scanner-safe confirmation

A token-bearing GET stores a short-lived claim cookie and redirects to this clean address. A clean GET shows the confirmation form. No GET creates an account or authenticated browser state.

Authentication: Public
Idempotency: A GET does not consume the one-use authentication token.

Parameters

AuthenticationToken

Responses

Status	Description
`200`	The clean confirmation form.
`303`	The token-bearing address redirects to the clean address.
`400`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

"<!doctype html><title>Confirm sign-in</title>"

POST

`/v1/auth/callback`

Confirm account access

Consumes the one-use claim after an explicit human POST and creates the authenticated browser cookie.

Authentication: Authentication claim cookie
Idempotency: The one-use claim can succeed once. A repeated confirmation fails safely.

Request example

{}

Responses

Status	Description
`303`	The confirmed owner continues to the dashboard.
`401`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

POST

`/v1/auth/logout`

End account access

Revokes the current human cookie and clears the browser authentication cookies.

Authentication: Human owner cookie
Idempotency: Repeated requests leave the browser signed out.

Parameters

MutationProof

Request example

{}

Responses

Status	Description
`204`	The browser is signed out.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

POST

`/v1/auth/magic-link`

Request an account access link

Sends the same neutral response for every valid email address. Email is only an authentication channel. Durable client and global limits suppress excess email without changing the response.

Authentication: Public
Idempotency: The cooldown and durable rate limits suppress extra messages and keep the same HTTP 202 response.

Request example

{
  "email": "[email protected]"
}

Responses

Status	Description
`202`	The neutral request result.
`400`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "ok": true
}

POST

`/v1/auth/signup`

Request a no-card account link

Sends a neutral authentication response for a new or existing email address. One normalized address has a 60-second message cooldown. Durable client and global limits suppress excess email without changing the response.

Authentication: Public
Idempotency: The cooldown and durable rate limits suppress extra messages and keep the same HTTP 202 response.

Request example

{
  "email": "[email protected]",
  "displayName": "Owner"
}

Responses

Status	Description
`202`	The neutral request result.
`400`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "ok": true
}

GET

`/v1/me`

Read the current principal and account

Returns the current human or agent identity and the authorized account.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Responses

Status	Description
`200`	The current authorized account.
`401`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "principal": {
    "id": "prn_example",
    "type": "human",
    "displayName": "Owner",
    "email": "[email protected]"
  },
  "account": {
    "id": "acc_example",
    "name": "Owner account",
    "plan": "free"
  }
}

Plans

POST

`/v1/billing/checkout`

Create hosted Checkout for Pro

Creates a hosted HTTPS Checkout page for the exact US$49 monthly Pro plan. IssueProbe does not receive card data.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Requires Idempotency-Key. An exact valid retry returns the same hosted Checkout page.

Parameters

IdempotencyKey
MutationProof

Request example

{}

Responses

Status	Description
`201`	The exact hosted Checkout URL.
`400`	The service returns a stable error code and a safe message.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`409`	The service returns a stable error code and a safe message.
`503`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "url": "https://checkout.stripe.com/c/pay/example",
  "replayed": false
}

POST

`/v1/billing/portal`

Create hosted subscription management

Creates a hosted HTTPS subscription-management page for a human owner with a managed customer.

Authentication: Human owner cookie
Idempotency: Each successful request creates a short-lived hosted management page.

Parameters

MutationProof

Request example

{}

Responses

Status	Description
`201`	The exact hosted management URL.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`409`	The service returns a stable error code and a safe message.
`503`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "url": "https://billing.stripe.com/p/example"
}

GET

`/v1/plan`

Read plan limits and monthly use

Returns the exact Free or Pro limits and current account use.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Responses

Status	Description
`200`	The current plan limits and use.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "plan": "free",
  "limits": {
    "websites": 1,
    "investigationsPerMonth": 3,
    "activeInvestigations": {
      "scope": "account",
      "count": 1
    },
    "artifactRetentionDays": 7
  },
  "usage": {
    "websites": 1,
    "investigationsStarted": 2,
    "reportsReceived": 4,
    "periodStartsAt": "2026-08-01T00:00:00Z",
    "periodEndsAt": "2026-09-01T00:00:00Z"
  }
}

GET

`/v1/subscription`

Read customer-safe subscription state

Returns the account plan and safe subscription state without external identifiers.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Responses

Status	Description
`200`	The safe subscription state.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "plan": "pro",
  "subscription": {
    "state": "active",
    "cancelAtPeriodEnd": false,
    "currentPeriodEndsAt": "2026-09-22T12:00:00Z"
  }
}

POST

`/v1/webhooks/stripe`

Receive one signed Stripe event

Verifies the exact raw body and complete IssueProbe product ownership before any local state change.

Authentication: Stripe signature
Idempotency: An owned event identifier applies once. A replay returns a duplicate outcome. A foreign event creates no local record.

Request example

{
  "id": "evt_example",
  "type": "customer.subscription.updated",
  "created": 1787400000,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_example"
    }
  }
}

Responses

Status	Description
`200`	The safe event outcome.
`400`	The service returns a stable error code and a safe message.
`503`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "received": true,
  "outcome": "applied"
}

Reports

GET

`/v1/metrics/useful-results`

Read customer review metrics

Returns the accepted-result rate and median report-to-ready time only when account data supports them.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Responses

Status	Description
`200`	Customer-safe review metrics.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "usefulResultRate": {
    "accepted": 3,
    "reviewed": 4,
    "rate": 0.75
  },
  "medianReportToReadyMs": 62000
}

GET

`/v1/reports`

List account reports

Filters customer-safe reports and uses a bounded opaque cursor.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Parameters

WebsiteFilter
ReportTypeFilter
ReportStateFilter
ReviewStateFilter
Cursor
Limit

Responses

Status	Description
`200`	A customer-safe report page.
`400`	The service returns a stable error code and a safe message.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "items": [
    {
      "id": "rpt_example",
      "reference": "IPR-1042",
      "website": {
        "id": "web_example",
        "name": "Example Site"
      },
      "type": "problem",
      "state": "ready_for_review",
      "summary": "The profile save request failed.",
      "conclusionStatus": "likely",
      "reviewState": "pending",
      "reviewDisposition": null,
      "receivedAt": "2026-08-22T14:00:02Z",
      "updatedAt": "2026-08-22T14:08:00Z"
    }
  ],
  "nextCursor": null
}

GET

`/v1/reports/{reportId}`

Read one customer-safe report

Returns the visitor report, safe browser evidence, source-backed result, unknown facts, recommended action, owner draft, review, plan use, and safe account activity.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Parameters

ReportId

Responses

Status	Description
`200`	One customer-safe report.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "report": {
    "id": "rpt_example",
    "reference": "IPR-1042",
    "website": {
      "id": "web_example",
      "name": "Example Site",
      "state": "ready"
    },
    "type": "problem",
    "description": "The save button does not finish.",
    "state": "ready_for_review",
    "page": {
      "url": "https://www.example.com/profile",
      "title": "Profile",
      "locale": "en-US",
      "timeZone": "UTC",
      "viewport": {
        "width": 1440,
        "height": 900
      }
    },
    "receivedAt": "2026-08-22T14:00:02Z",
    "updatedAt": "2026-08-22T14:08:00Z",
    "archivedAt": null
  },
  "browserEvidence": {
    "console": [],
    "network": [],
    "browserState": {
      "cookies": [],
      "formFields": [],
      "localStorage": []
    }
  },
  "result": {
    "schemaVersion": 1,
    "reportSummary": {
      "title": "Profile save request fails",
      "visitorSummary": "The visitor cannot save profile changes.",
      "technicalSummary": "The active save branch can fail."
    },
    "classification": {
      "reportType": "problem",
      "confidence": 0.82,
      "reason": "The visitor and source evidence describe the same save path."
    },
    "conclusion": {
      "status": "likely",
      "summary": "The active save path does not handle an absent field.",
      "confidence": 0.82,
      "evidenceIds": [
        "EV-001",
        "EV-002"
      ],
      "limits": "The affected visitor count is unknown."
    },
    "evidence": [
      {
        "id": "EV-001",
        "type": "browser_network",
        "description": "The save request returned an error.",
        "excerpt": "POST /api/profile -> 500 in 412 ms",
        "observedAt": "2026-08-22T14:00:01Z",
        "source": {
          "kind": "visitor_browser",
          "reference": "report-network-1"
        }
      },
      {
        "id": "EV-002",
        "type": "source_code",
        "description": "The active branch uses an absent field without a check.",
        "excerpt": "const zone = profile.timeZone.trim()",
        "observedAt": "2026-08-22T14:06:30Z",
        "source": {
          "kind": "repository",
          "repositoryRevision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "path": "src/routes/profile.ts",
          "lineStart": 118,
          "lineEnd": 124
        }
      }
    ],
    "unknowns": [
      {
        "fact": "The affected visitor count",
        "whyUnknown": "The evidence contains one report.",
        "nextEvidence": "Review an approved aggregate before a production decision."
      }
    ],
    "recommendedAction": {
      "type": "code_change",
      "summary": "Handle the absent field before the save path uses it.",
      "steps": [
        "Add a safe branch.",
        "Add a focused regression test."
      ],
      "risk": "low",
      "requiresHumanApproval": true,
      "evidenceIds": [
        "EV-002"
      ]
    },
    "draftResponse": {
      "body": "Thank you for the report. The owner will review the save behavior.",
      "claimsEvidenceIds": [
        "EV-001",
        "EV-002"
      ]
    }
  },
  "artifacts": [],
  "draftResponse": {
    "body": "Thank you for the report.",
    "source": "result",
    "updatedAt": null
  },
  "review": null,
  "planUse": {
    "plan": "free",
    "limits": {
      "websites": 1,
      "investigationsPerMonth": 3,
      "activeInvestigations": {
        "scope": "account",
        "count": 1
      },
      "artifactRetentionDays": 7
    },
    "usage": {
      "websites": 1,
      "investigationsStarted": 1,
      "reportsReceived": 1,
      "periodStartsAt": "2026-08-01T00:00:00Z",
      "periodEndsAt": "2026-09-01T00:00:00Z"
    }
  },
  "auditHistory": [],
  "investigationElapsedMs": 60000
}

POST

`/v1/reports/{reportId}/archive`

Archive one report

Uses an explicit report transition and cancels queued work without a quota refund.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Repeated requests leave the report archived.

Parameters

ReportId
MutationProof

Request example

{}

Responses

Status	Description
`200`	The archived report state.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`409`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "report": {
    "id": "rpt_example",
    "state": "archived"
  }
}

GET

`/v1/reports/{reportId}/artifacts/{artifactId}`

Read one authorized screenshot

Checks the exact account, website, report, artifact, media type, safety state, and retention time.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Parameters

ReportId
ArtifactId

Responses

Status	Description
`200`	An approved PNG, JPEG, or WebP screenshot.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`410`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

"binary image data"

PUT

`/v1/reports/{reportId}/draft-response`

Save one owner draft revision

Appends an owner draft outside the immutable result. This operation sends no visitor message.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Each successful request appends a new draft revision.

Parameters

ReportId
MutationProof

Request example

{
  "body": "Thank you for the report. The owner will review the next change."
}

Responses

Status	Description
`200`	The saved draft revision.
`400`	The service returns a stable error code and a safe message.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "draftResponse": {
    "body": "Thank you for the report. The owner will review the next change.",
    "source": "owner",
    "updatedAt": "2026-08-22T14:10:00Z"
  }
}

POST

`/v1/reports/{reportId}/investigations`

Request one new investigation

Rechecks report state, website readiness, monthly quota, and active limits before one follow-up investigation.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Requires Idempotency-Key. An exact retry returns the first safe result. A changed request with the same key fails.

Parameters

ReportId
IdempotencyKey
MutationProof

Request example

{}

Responses

Status	Description
`202`	One new investigation is queued.
`400`	The service returns a stable error code and a safe message.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`409`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "report": {
    "id": "rpt_example",
    "state": "queued"
  },
  "investigation": {
    "state": "queued"
  },
  "replayed": false
}

POST

`/v1/reports/{reportId}/review`

Record one human review decision

Appends one human disposition outside the immutable result.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: One report result accepts one review decision. A conflicting repeated decision fails safely.

Parameters

ReportId
MutationProof

Request example

{
  "disposition": "accepted_with_edits"
}

Responses

Status	Description
`201`	The saved human review decision.
`400`	The service returns a stable error code and a safe message.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`409`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "review": {
    "disposition": "accepted_with_edits",
    "reviewedAt": "2026-08-22T14:12:00Z"
  }
}

Public reports

POST

`/v1/public/reports`

Create one exact-origin website report

Stores a problem or suggestion with bounded approved evidence. An optional screenshot must match explicit consent.

Authentication: Public
Idempotency: Requires Idempotency-Key. An exact request replays its first safe result for 24 hours. A changed request with the same key fails.

Parameters

WebsiteKeyQuery
OriginHeader
IdempotencyKey
PublicClient

Request example

{
  "payload": "{\"websiteKey\":\"ip_widget_example\",\"type\":\"problem\",\"description\":\"The save button does not finish.\",\"page\":{\"url\":\"https://www.example.com/profile\",\"title\":\"Profile\",\"locale\":\"en-US\",\"timeZone\":\"UTC\",\"viewport\":{\"width\":1440,\"height\":900}},\"console\":[],\"network\":[],\"browserState\":{\"cookies\":[],\"formFields\":[],\"localStorage\":[]},\"consent\":{\"screenshot\":false,\"evidence\":true}}"
}

Responses

Status	Description
`201`	The stored report and safe investigation state.
`400`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`409`	The service returns a stable error code and a safe message.
`429`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "report": {
    "id": "rpt_example",
    "reference": "IPR-1042",
    "state": "queued",
    "receivedAt": "2026-08-22T14:00:02Z"
  },
  "investigation": {
    "state": "queued"
  }
}

OPTIONS

`/v1/public/reports`

Check exact-origin report access

Allows the documented report headers only for a ready website and exact verified origin.

Authentication: Public
Idempotency: Safe preflight. Repeated requests do not change state.

Parameters

WebsiteKeyQuery
OriginHeader

Responses

Status	Description
`204`	The exact origin can submit a report.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

GET

`/v1/public/widget-config`

Read exact-origin widget configuration

Returns configuration only when the public widget key and request Origin match one verified website.

Authentication: Public
Idempotency: Safe read. Repeated requests do not change state.

Parameters

WebsiteKeyQuery
OriginHeader

Responses

Status	Description
`200`	The public widget configuration.
`400`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "website": {
    "name": "Example Site",
    "position": "right"
  },
  "reportTypes": [
    "problem",
    "suggestion"
  ],
  "evidence": {
    "screenshot": true,
    "console": true,
    "network": true,
    "browserStateMetadata": true,
    "maxScreenshotBytes": 5242880
  },
  "privacyUrl": "https://issueprobe.com/privacy/widget"
}

Websites

GET

`/v1/websites`

List authorized websites

Returns account websites with origin and repository readiness states.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Responses

Status	Description
`200`	The authorized website list.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "items": [
    {
      "id": "web_example",
      "name": "Example Site",
      "state": "ready",
      "primaryOrigin": "https://www.example.com",
      "position": "right",
      "repositoryState": "ready",
      "verifiedOriginCount": 1,
      "updatedAt": "2026-08-22T12:00:00Z"
    }
  ]
}

POST

`/v1/websites`

Register one website and repository

Creates one website, exact origin, public widget key, and website-specific read-only deploy key.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: This operation does not accept an idempotency key. A successful request creates one website.

Parameters

MutationProof

Request example

{
  "name": "Example Site",
  "primaryOrigin": "https://www.example.com",
  "position": "right",
  "repository": {
    "sshUrl": "[email protected]:owner/site.git",
    "defaultBranch": "main",
    "hostKeyFingerprint": "SHA256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
  }
}

Responses

Status	Description
`201`	The new website and public deploy key.
`400`	The service returns a stable error code and a safe message.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`409`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "website": {
    "id": "web_example",
    "name": "Example Site",
    "state": "needs_origin_proof",
    "primaryOrigin": "https://www.example.com",
    "publicWidgetKey": "ip_widget_example",
    "position": "right"
  },
  "repository": {
    "state": "needs_deploy_key",
    "publicDeployKey": "ssh-ed25519 AAAAexample issueprobe-web_example"
  }
}

GET

`/v1/websites/{websiteId}`

Read one website setup

Returns exact origins, public well-known proof publication data, the neutral repository revision mode and current revision, evidence settings, plan limits, and readiness.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Parameters

WebsiteId

Responses

Status	Description
`200`	One authorized website.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "website": {
    "id": "web_example",
    "name": "Example Site",
    "state": "ready",
    "primaryOrigin": "https://www.example.com",
    "publicWidgetKey": "ip_widget_example",
    "position": "right",
    "createdAt": "2026-08-22T12:00:00Z",
    "updatedAt": "2026-08-22T12:00:00Z"
  },
  "origins": [
    {
      "id": "orgn_example",
      "origin": "https://www.example.com",
      "state": "pending",
      "proofMethod": null,
      "verifiedAt": null,
      "verification": {
        "method": "well_known",
        "url": "https://www.example.com/.well-known/issueprobe-verification.txt",
        "content": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      }
    }
  ],
  "repository": {
    "sshUrl": "[email protected]:owner/site.git",
    "defaultBranch": "main",
    "deployedRevision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "revisionMode": "branch_head",
    "publicDeployKey": "ssh-ed25519 AAAAexample issueprobe-web_example",
    "state": "ready",
    "lastCheckedAt": "2026-08-22T12:00:00Z",
    "lastErrorCode": null
  },
  "evidenceSettings": {
    "screenshot": true,
    "console": true,
    "network": true,
    "browserStateMetadata": true
  },
  "limits": {
    "websites": 1,
    "investigationsPerMonth": 3,
    "activeInvestigations": {
      "scope": "account",
      "count": 1
    },
    "artifactRetentionDays": 7
  },
  "readiness": {
    "originVerified": true,
    "repositoryReady": true,
    "widgetReady": true
  }
}

PATCH

`/v1/websites/{websiteId}`

Update a website name or widget position

Changes only the website name or left-right widget position.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Repeating the same fields leaves the same website settings.

Parameters

WebsiteId
MutationProof

Request example

{
  "name": "Example Product",
  "position": "left"
}

Responses

Status	Description
`200`	The updated website setup.
`400`	The service returns a stable error code and a safe message.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "website": {
    "id": "web_example",
    "name": "Example Product",
    "position": "left"
  }
}

POST

`/v1/websites/{websiteId}/deploy-key/rotate`

Rotate one website deploy key

Creates a replacement website-specific key and returns only its public value.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: This operation creates a new key pair on each successful request.

Parameters

WebsiteId
MutationProof

Request example

{}

Responses

Status	Description
`200`	The replacement public deploy key.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`503`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "state": "needs_deploy_key",
  "publicDeployKey": "ssh-ed25519 AAAAexample issueprobe-web_example"
}

PUT

`/v1/websites/{websiteId}/evidence-settings`

Replace evidence category settings

Enables or disables fixed categories. No setting can enable cookie, form, or local-storage values.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Repeating the same category states leaves the same settings.

Parameters

WebsiteId
MutationProof

Request example

{
  "screenshot": true,
  "console": true,
  "network": true,
  "browserStateMetadata": true
}

Responses

Status	Description
`200`	The fixed category settings.
`400`	The service returns a stable error code and a safe message.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "evidenceSettings": {
    "screenshot": true,
    "console": true,
    "network": true,
    "browserStateMetadata": true
  }
}

GET

`/v1/websites/{websiteId}/install`

Read the widget installation snippet

Returns the versioned widget snippet and exact verified origins.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Parameters

WebsiteId

Responses

Status	Description
`200`	The widget installation data.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "script": "<script src=\"https://issueprobe.com/widget/v1/issueprobe.js\" data-website=\"ip_widget_example\" async></script>",
  "verifiedOrigins": [
    "https://www.example.com"
  ]
}

POST

`/v1/websites/{websiteId}/origins`

Add one exact website origin

Normalizes a root HTTP or HTTPS origin and stores it in a pending state.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: A duplicate normalized origin fails with a stable conflict error.

Parameters

WebsiteId
MutationProof

Request example

{
  "origin": "https://app.example.com/"
}

Responses

Status	Description
`201`	The pending exact origin.
`400`	The service returns a stable error code and a safe message.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`409`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "origin": {
    "id": "orgn_example",
    "origin": "https://app.example.com",
    "state": "pending"
  }
}

POST

`/v1/websites/{websiteId}/origins/{originId}/verify`

Verify control of one exact origin

Fetches the exact HTTPS well-known file without credentials or redirects and requires the exact public proof text.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: A repeated successful proof performs no fetch and adds no duplicate audit event.

Parameters

WebsiteId
OriginId
MutationProof

Request example

{
  "method": "well_known"
}

Responses

Status	Description
`200`	The verified exact origin.
`400`	The service returns a stable error code and a safe message.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`409`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "origin": {
    "id": "orgn_example",
    "origin": "https://www.example.com",
    "state": "verified",
    "verifiedAt": "2026-08-22T12:00:00Z"
  }
}

GET

`/v1/websites/{websiteId}/readiness`

Read website readiness

Returns safe origin, repository, and widget readiness states.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Safe read. Repeated requests do not change state.

Parameters

WebsiteId

Responses

Status	Description
`200`	The website readiness state.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "state": "ready",
  "checks": {
    "origin": "ready",
    "repository": "ready",
    "widget": "ready"
  }
}

POST

`/v1/websites/{websiteId}/repository/check`

Check read-only repository access

Checks read-only access. Branch-head mode records the current remote branch head. Pinned mode preserves the owner-supplied revision.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: Each successful branch-head check can refresh the current revision. A pinned check preserves its revision.

Parameters

WebsiteId
MutationProof

Request example

{}

Responses

Status	Description
`200`	The safe repository readiness result.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`503`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "state": "ready",
  "deployedRevision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "errorCode": null,
  "checkedAt": "2026-08-22T12:00:00Z"
}

POST

`/v1/websites/{websiteId}/widget-key/rotate`

Rotate one public widget key

Replaces the public website identifier. The old identifier stops reading configuration or creating reports.

Authentication: Human owner cookie or Scoped agent credential
Idempotency: This operation creates a new public identifier on each successful request.

Parameters

WebsiteId
MutationProof

Request example

{}

Responses

Status	Description
`200`	The replacement public widget key.
`401`	The service returns a stable error code and a safe message.
`403`	The service returns a stable error code and a safe message.
`404`	The service returns a stable error code and a safe message.
`default`	The service returns a stable error code and a safe message.

Response example

{
  "publicWidgetKey": "ip_widget_example"
}

One public contract for human and agent product actions.

Base URL

Agent enrollment

/agent-enrollment/authorize

Responses

Response example

/agent-enrollment/authorize

Parameters

Request example

Responses

Response example

/v1/agent-enrollments

Parameters

Request example

Responses

Response example

/v1/agent-enrollments/authorize

Parameters

Responses

/v1/agent-enrollments/{enrollmentId}/exchange

Parameters

Request example

Responses

Response example

Service

/healthz

Responses

Response example

/readyz

Responses

Response example

/version

Responses

Response example

Documentation

/openapi.json

Responses

Response example

API credentials

/v1/api-credentials

Responses

Response example

/v1/api-credentials

Parameters

Request example

Responses

Response example

/v1/api-credentials/{credentialId}

Parameters

Responses

Account

/v1/audit-events

Responses

Response example

Authentication

/v1/auth/callback

Parameters

Responses

Response example

/v1/auth/callback

Request example

Responses

/v1/auth/logout

Parameters

Request example

Responses

/v1/auth/magic-link

Request example

Responses

Response example

/v1/auth/signup

Request example

Responses

Response example

/v1/me

Responses

Response example

Plans

/v1/billing/checkout

Parameters

`/agent-enrollment/authorize`

`/agent-enrollment/authorize`

`/v1/agent-enrollments`

`/v1/agent-enrollments/authorize`

`/v1/agent-enrollments/{enrollmentId}/exchange`

`/healthz`

`/readyz`

`/version`

`/openapi.json`

`/v1/api-credentials`

`/v1/api-credentials`

`/v1/api-credentials/{credentialId}`

`/v1/audit-events`

`/v1/auth/callback`

`/v1/auth/callback`

`/v1/auth/logout`

`/v1/auth/magic-link`

`/v1/auth/signup`

`/v1/me`

`/v1/billing/checkout`

`/v1/billing/portal`

`/v1/plan`

`/v1/subscription`

`/v1/webhooks/stripe`

`/v1/metrics/useful-results`

`/v1/reports`

`/v1/reports/{reportId}`

`/v1/reports/{reportId}/archive`

`/v1/reports/{reportId}/artifacts/{artifactId}`

`/v1/reports/{reportId}/draft-response`

`/v1/reports/{reportId}/investigations`

`/v1/reports/{reportId}/review`

`/v1/public/reports`

`/v1/public/reports`

`/v1/public/widget-config`

`/v1/websites`