REST API

The DepAegis REST API provides programmatic access to packages, organizations, tokens, scan results, and SBOMs. All endpoints use JSON for request and response bodies.

Base URL

All API requests are made to the DepAegis API:

https://app.depaegis.com/api/v1

Authentication

All API endpoints require authentication via a bearer token in the Authorization header:

Authorization: Bearer depa_tok_abc123def456...

Create tokens via the DepAegis dashboard (Settings → Access Tokens) or programmatically using the POST /api/v1/tokens endpoint.

Endpoints

Packages

List Packages

GET /api/v1/packages

Returns a paginated list of all packages the authenticated user can access.

# Example request
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.depaegis.com/api/v1/packages?limit=10&org=myorg"

# Response
{
  "items": [
    {
      "name": "@myorg/ui-components",
      "type": "npm",
      "org": "myorg",
      "latestVersion": "2.1.0",
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ],
  "cursor": "eyJpZCI6MTAwfQ==",
  "hasMore": true
}

Get Package Details

GET /api/v1/packages/:name

Returns metadata for a specific package including all versions.

# Example
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.depaegis.com/api/v1/packages/@myorg%2Fui-components"

List Versions

GET /api/v1/packages/:name/versions

Returns all published versions of a package.

Delete Version

DELETE /api/v1/packages/:name/versions/:version

Permanently deletes a specific version. Requires admin or ownerrole in the package's organization.

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.depaegis.com/api/v1/packages/@myorg%2Fui-components/versions/1.0.0"

Organizations

List Organizations

GET /api/v1/orgs

Returns all organizations the authenticated user belongs to.

List Organization Members

GET /api/v1/orgs/:org/members

Returns members of an organization. Requires member role or higher.

# Example response
{
  "items": [
    {
      "userId": "usr_abc123",
      "email": "alice@example.com",
      "role": "owner",
      "joinedAt": "2025-06-01T08:00:00Z"
    },
    {
      "userId": "usr_def456",
      "email": "bob@example.com",
      "role": "publisher",
      "joinedAt": "2025-08-15T14:30:00Z"
    }
  ]
}

Access Tokens

Create Access Token

POST /api/v1/tokens

Creates a new personal access token. The raw token value is returned only once in the response.

# Request
{
  "name": "ci-publish-token",
  "scope": "publish",
  "expiresIn": "30d"
}

# Response
{
  "id": "tok_abc123",
  "name": "ci-publish-token",
  "scope": "publish",
  "token": "depa_tok_abc123def456...",
  "expiresAt": "2026-07-11T00:00:00Z",
  "createdAt": "2026-06-11T00:00:00Z"
}

Revoke Token

DELETE /api/v1/tokens/:id

Revokes a token by its ID. Any subsequent requests using the revoked token will return 401 Unauthorized.

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.depaegis.com/api/v1/tokens/tok_abc123"

Security

Get Scan Results

GET /api/v1/packages/:name/scan

Returns vulnerability scan results for the latest version of a package. Use the version query parameter to scan a specific version.

# Response
{
  "package": "@myorg/ui-components",
  "version": "2.1.0",
  "scannedAt": "2026-06-11T12:00:00Z",
  "status": "completed",
  "vulnerabilities": [
    {
      "id": "CVE-2026-12345",
      "severity": "high",
      "summary": "Prototype pollution in dependency",
      "affectedRange": "<2.0.0",
      "fixedIn": "2.0.1"
    }
  ],
  "summary": {
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 0
  }
}

Download SBOM

GET /api/v1/packages/:name/sbom

Downloads the Software Bill of Materials for a package in CycloneDX format. Accepts an optional version query parameter.

curl -H "Authorization: Bearer $TOKEN" \
  "https://app.depaegis.com/api/v1/packages/@myorg%2Fui-components/sbom?version=2.1.0" \
  -o sbom.json

Pagination

List endpoints use cursor-based pagination. Each response includes a cursor field and a hasMore boolean:

{
  "items": [...],
  "cursor": "eyJpZCI6MTAwfQ==",
  "hasMore": true
}

Pass the cursor value as a query parameter in the next request to fetch the next page. When hasMore is false, there are no more results.

# First page
GET /api/v1/packages?limit=10

# Next page
GET /api/v1/packages?limit=10&cursor=eyJpZCI6MTAwfQ==

Error Response Format

Errors are returned as JSON with a consistent structure:

{
  "error": {
    "code": "PACKAGE_NOT_FOUND",
    "message": "Package '@myorg/missing-pkg' not found",
    "details": {
      "name": "@myorg/missing-pkg"
    }
  }
}

Rate Limiting

The API enforces rate limits to protect the service. Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1718100000

Default rate limits by token scope: