API reference

Complete documentation for all ShipOS REST API endpoints. Build faster with enterprise-grade backend services. Start integrating in minutes with examples for every endpoint.

https://api.shipos.dev/v1

Get your API keys from your ShipOS dashboard under Project Settings. Use test keys for development and live keys for production.

Authorization: Bearer ship_live_your_api_key_here

Get your API keys from your ShipOS dashboard under Project Settings. Use test keys for development and live keys for production.

Authorization: Bearer ship_live_your_api_key_here

Get your API keys from your ShipOS dashboard under Project Settings. Use test keys for development and live keys for production.

Authorization: Bearer ship_live_your_api_key_here

Authentication

ShipOS API uses API key authentication. Include your API key in the Authorization header of every request.

# Example API request with authentication
curl -X GET \
 -H "Authorization: Bearer ship_live_..." \
 -H "Content-Type: application/json" \
 https://api.shipos.dev/v1/auth/users

User management

Create and manage user accounts with secure authentication flows.

POST

/auth/users

Create a new user account with email and password authentication.

Request

Parameter

Type

Required

String

Required

Password

String

Required

Name

String

Optional

Response

{
 "id": "usr_1234567890",
 "email": "user@example.com",
 "name": "John Doe",
 "email_verified": false,
 "created_at": "2024-01-15T10:30:00Z"
}

201

User created successfully

400

Invalid request data

409

Email already exists

GET

/auth/users/{user_id}

Retrieve a specific user by their unique identifier.

Path Parameters

Parameter

Type

Description

user_id

String

Unique user identifier

Response

{
 "id": "usr_1234567890",
 "email": "user@example.com",
 "name": "John Doe",
 "email_verified": true,
 "created_at": "2024-01-15T10:30:00Z"
}

200

User retrieved successfully

404

User not found

Monetization

Manage user subscriptions, billing cycles, and payment processing with Stripe integration.

POST

/billing/subscriptions

Create a new subscription for a user with automated billing.

Request

{
 "user_id": "usr_1234567890",
 "plan_id": "plan_growth_monthly",
 "payment_method": "pm_card_visa",
 "trial_days": 14
}

Response

{
 "id": "sub_1234567890",
 "user_id": "usr_1234567890",
 "status": "trialing",
 "current_period_end": "2024-01-29T10:30:00Z",
 "trial_end": "2024-01-29T10:30:00Z"
}

201

Subscription created

400

Invalid payment method

Rate limits

ShipOS implements fair usage rate limiting to ensure optimal performance for all users.

Starter Plan

1,000

requests per minute

Growth Plan

5,000

requests per minute

Scale Plan

10,000

requests per minute

Every API response includes headers to help you track your usage:

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1642694400

Every API response includes headers to help you track your usage:

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1642694400

Every API response includes headers to help you track your usage:

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1642694400

Webhooks

Receive real-time notifications about events in your ShipOS account via webhook endpoints.

POST

/webhooks

Request

{
 "url": "https://your-app.com/webhooks",
 "events": [
   "user.created",
   "subscription.created",
   "invoice.paid"
 ]
}

Response

{
 "id": "wh_1234567890",
 "url": "https://your-app.com/webhooks",
 "events": [
   "user.created",
   "..."
 ],
 "status": "active",
 "created_at": "2024-01-15T10:30:00Z"
}

Available events

Receive real-time notifications about events in your ShipOS account via webhook endpoints.

user.created

New user account created

user.updated

User profile updated

subscription.created

New subscription started

invoice.paid

Invoice payment successful

Quick access

Authentication

User management

Monetization

Rate limits

Webhooks