API overview

The BIMP HTTP API exposes supported organization, repository, policy, remediation, Exception, reporting, audit, and integration workflows. The web application and automation use the same product authorization model.

Base URL and contract

Use the origin of your BIMP environment:

https://<your-bimp-host>

The generated OpenAPI 3.1 contract is available from that environment at:

GET /api/v1/openapi.json

Treat the runtime document as the source of truth for available paths, methods, request schemas, response schemas, and permission metadata. This guide explains the conventions around it; it does not duplicate several hundred endpoints and then hope they stay friends.

Authentication

Browser sessions

The BIMP web application authenticates API requests with the Better Auth session cookie issued during sign-in. Do not copy a browser session into automation.

Organization API keys

Create machine credentials under Settings → Automation → API keys. Each key is bound to an organization-owned service account and receives either a role or an explicit set of permissions.

BIMP shows the complete secret only in the create response. Copy it into your secret manager immediately. Store neither the key nor provider credentials in a repository, policy reason, event payload, or build log.

Present the key on an organization-scoped request with x-api-key:

curl \
  --header "x-api-key: $BIMP_API_KEY" \
  --header "accept: application/json" \
  "https://<your-bimp-host>/api/v1/org/<organization-id>/repositories"

The organization ID in the path must match the organization bound to the key. A key cannot use a broader path to cross that boundary.

Attenuate machine access

Prefer the smallest role or explicit permission set that can perform the job. BIMP checks both the service-account authority and the requested resource. A key with draft mapping permission, for example, does not gain publication or member management authority by being used from a trusted host.

Keys can have an expiry from 1 to 365 days or an explicitly unlimited expiry, depending on the creation choice. Revoke a key from the API keys page when it is no longer needed. Revocation disables the credential while retaining metadata needed for audit.

Requests

Organization product routes use this general shape:

/api/v1/org/{orgId}/...

Send JSON request bodies with content-type: application/json. Use the exact path, query, and body schema in the OpenAPI contract. Resource IDs are opaque; do not derive or reuse one across organizations.

List endpoints may use cursor pagination. Follow the returned cursor rather than constructing one. Timestamps are ISO 8601 values unless a route documents another representation.

Responses and errors

Successful JSON responses use the status code documented for the route. Create operations commonly return 201; successful deletions may return 204 with no body.

Common failures include:

Status	Meaning
400	The request did not match the accepted input or business rule.
401	No valid session or organization API key was supplied.
403	The authenticated identity lacks authority for the action.
404	The resource is unavailable in the active organization context.
409	The request conflicts with current workflow state.
429	A rate or upstream budget requires the caller to slow down.

Read the returned error message, but do not expose raw responses blindly to end users or logs. A 404 can intentionally avoid revealing a resource outside the caller’s tenant context.

Safe automation pattern

1. Create a dedicated key with the narrowest useful access.
2. Read the runtime OpenAPI contract during client development.
3. Validate input before sending it.
4. Treat retries as potentially repeated delivery and use stable identifiers where the route provides them.
5. Record the request outcome without recording credentials or sensitive provider content.
6. Revoke or rotate access when the job, owner, or environment changes.

For event-driven automation, use Webhooks and event destinations instead of polling every resource on a tight loop.