API Reference

The DevBar REST API base URL is https://api.devbar.app. All endpoints are prefixed with /api/v1.

Authentication: Endpoints marked Auth required require a Bearer token in the Authorization header: Authorization: Bearer <access_token>

Rate Limits: Most authenticated endpoints allow 120 requests per minute per user. Authentication endpoints (login, register) are limited to 10 requests per 15 minutes per IP. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers. When rate-limited you receive a 429 response.

Base URL: https://api.devbar.app/api/v1. EU customers use https://eu.api.devbar.app/api/v1.

Authentication OAuth Device Auth SAML Users Tokens Organisation Workflows Admin Webhooks SCIM WebSocket Request / Response Examples

Authentication

Method	Path	Description	Auth
POST	/auth/register	Register a new user account	—
POST	/auth/login	Sign in and receive access + refresh tokens	—
POST	/auth/refresh	Exchange a refresh token for a new access token	—
POST	/auth/forgot-password	Request a password-reset email	—
POST	/auth/reset-password	Reset password using the emailed token	—
POST	/auth/verify-email	Verify email address with the emailed code	—

OAuth

Method	Path	Description	Auth
GET	/auth/google	Initiate Google OAuth flow	—
GET	/auth/github	Initiate GitHub OAuth flow	—

Device Auth

Method	Path	Description	Auth
POST	/auth/device/authorize	Start device authorisation flow (returns device_code)	—
GET	/auth/device/status	Poll for device authorisation status	—
POST	/auth/device/complete	Complete device auth and issue tokens	—

SAML

Method	Path	Description	Auth
GET	/saml/metadata	SP metadata XML for IdP configuration	—
GET	/saml/login	Redirect to IdP login page	—
POST	/saml/acs	Assertion Consumer Service — receives SAML response	—

Users

Method	Path	Description	Auth
GET	/users/me	Get the authenticated user's profile	Required
PATCH	/users/me	Update profile fields (name, email)	Required
GET	/users/me/features	List feature flags enabled for the user	Required

Tokens

Method	Path	Description	Auth
GET	/tokens	List all API tokens for the authenticated user	Required
POST	/tokens	Create a new API token	Required
GET	/tokens/:id	Get a specific token by ID	Required
DELETE	/tokens/:id	Revoke a token	Required

Organisation

Method	Path	Description	Auth
GET	/org	Get the authenticated user's organisation	Required
PATCH	/org	Update organisation settings	Required
GET	/org/members	List organisation members	Required
DELETE	/org/members/:userId	Remove a member from the organisation	Required
GET	/org/invitations	List pending invitations	Required
POST	/org/invitations	Invite a user by email	Required
DELETE	/org/invitations/:id	Cancel a pending invitation	Required

Workflows

Method	Path	Description	Auth
GET	/workflows	List all workflows for the organisation	Required
POST	/workflows	Create a new workflow	Required
GET	/workflows/:id	Get a workflow by ID	Required
PUT	/workflows/:id	Replace a workflow definition	Required
DELETE	/workflows/:id	Delete a workflow	Required
GET	/workflows/marketplace	Browse the workflow marketplace	Required

Admin

Method	Path	Description	Auth
GET	/admin/users	List all users (admin only)	Required
GET	/admin/orgs	List all organisations (admin only)	Required
GET	/admin/features	List all feature flags	Required
PUT	/admin/features/:key	Enable / disable a feature flag	Required
GET	/admin/plans	List available plans	Required
GET	/admin/audit-log	Query the audit log	Required
GET	/admin/email-config	Get email provider configuration	Required
PUT	/admin/email-config	Update email provider configuration	Required
GET	/admin/saml-config	Get SAML configuration	Required
PUT	/admin/saml-config	Update SAML configuration	Required

Webhooks

Method	Path	Description	Auth
POST	/webhooks/stripe	Stripe billing events	—
POST	/webhooks/pagerduty	PagerDuty incident events	—
POST	/webhooks/github	GitHub push / PR events	—
POST	/webhooks/datadog	Datadog monitor alert events	—

SCIM

Method	Path	Description	Auth
GET	/scim/v2/Users	List SCIM users	Required
POST	/scim/v2/Users	Provision a new user	Required
GET	/scim/v2/Users/:id	Get a SCIM user by ID	Required
PUT	/scim/v2/Users/:id	Replace a SCIM user	Required
PATCH	/scim/v2/Users/:id	Partially update a SCIM user	Required
DELETE	/scim/v2/Users/:id	Deprovision a SCIM user	Required

WebSocket

Method	Path	Description	Auth
GET	/ws	WebSocket upgrade endpoint for real-time events	Required

Request / Response Examples

Curl examples for the most commonly used endpoints. Replace bearer tokens with your own.

Authentication

POST /api/v1/auth/login

Request

curl -X POST https://api.devbar.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "s3cret!"}'

Response (200)

{
  "data": {
    "user": { "id": "usr_abc123", "email": "[email protected]", "name": "Jane Doe" },
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
  }
}

Errors

401 Invalid credentials
429 Rate limited (10 req/15min)

POST /api/v1/auth/register

Request

curl -X POST https://api.devbar.app/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "[email protected]", "password": "s3cret!"}'

Response (201)

{
  "data": {
    "user": { "id": "usr_abc123", "email": "[email protected]", "name": "Jane Doe" },
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
  }
}

Errors

409 Email already registered
422 Validation error (weak password, invalid email)

POST /api/v1/auth/refresh

Request

curl -X POST https://api.devbar.app/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "dGhpcyBpcyBhIHJlZnJl..."}'

Response (200)

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "bmV3IHJlZnJlc2ggdG9r..."
  }
}

Errors

401 Invalid or expired refresh token

Tokens

POST /api/v1/tokens/verify

Request

curl -X POST https://api.devbar.app/api/v1/tokens/verify \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200)

{
  "data": {
    "valid": true,
    "user_id": "usr_abc123",
    "scopes": ["read", "write"],
    "expires_at": "2026-05-01T00:00:00Z"
  }
}

Errors

401 Token invalid or expired

POST /api/v1/tokens

Request

curl -X POST https://api.devbar.app/api/v1/tokens \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Pipeline", "scopes": ["read"]}'

Response (201)

{
  "data": {
    "id": "tok_xyz789",
    "name": "CI Pipeline",
    "token": "dvb_live_abc123...",
    "scopes": ["read"],
    "created_at": "2026-04-24T12:00:00Z"
  }
}

Errors

401 Unauthorized
422 Invalid scopes or missing name

GET /api/v1/tokens

Request

curl https://api.devbar.app/api/v1/tokens \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200)

{
  "data": [
    {
      "id": "tok_xyz789",
      "name": "CI Pipeline",
      "scopes": ["read"],
      "last_used_at": "2026-04-23T18:30:00Z",
      "created_at": "2026-04-01T12:00:00Z"
    }
  ]
}

Errors

401 Unauthorized

Billing

GET /api/v1/billing/plans

Request

curl https://api.devbar.app/api/v1/billing/plans \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200)

{
  "data": [
    { "id": "plan_solo", "name": "Solo", "price_monthly": 0, "max_integrations": 5 },
    { "id": "plan_pro", "name": "Pro", "price_monthly": 12, "max_integrations": 21 },
    { "id": "plan_team", "name": "Team", "price_monthly": 24, "max_integrations": 21, "max_seats": 50 },
    { "id": "plan_enterprise", "name": "Enterprise", "price_monthly": null, "max_integrations": 21, "max_seats": null }
  ]
}

Errors

401 Unauthorized

POST /api/v1/billing/checkout

Request

curl -X POST https://api.devbar.app/api/v1/billing/checkout \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"plan_id": "plan_pro", "billing_cycle": "monthly"}'

Response (200)

{
  "data": {
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
    "session_id": "cs_live_abc123"
  }
}

Errors

401 Unauthorized
400 Already subscribed to this plan

Announcements

GET /api/v1/announcements

Request

curl https://api.devbar.app/api/v1/announcements \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200)

{
  "data": [
    {
      "id": "ann_001",
      "title": "v1.3.0 Released",
      "body": "Free trial and storage provider choice now available.",
      "created_at": "2026-04-20T10:00:00Z",
      "reactions": { "thumbsup": 12, "heart": 5, "rocket": 8 }
    }
  ]
}

Errors

401 Unauthorized

POST /api/v1/announcements/:id/react

Request

curl -X POST https://api.devbar.app/api/v1/announcements/ann_001/react \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"emoji": "rocket"}'

Response (200)

{
  "data": {
    "announcement_id": "ann_001",
    "emoji": "rocket",
    "count": 9
  }
}

Errors

401 Unauthorized
404 Announcement not found
422 Invalid emoji type