API overview

Create projects, deploy code, and operate your installation from an application or script. Each resource has one reference page: shared behavior and fields, with SDK and REST API tabs for examples.

Start here

Ship SDK ships in openship 0.8.0 and later. Start with npm install openship and the SDK guide.

Make a request

Use a token that can read projects in your organization. The SDK returns the application result; REST returns the endpoint's JSON response.

import { OpenshipClient } from "openship";

const token = process.env.OPENSHIP_TOKEN;
const organizationId = process.env.OPENSHIP_ORGANIZATION_ID;
if (!token || !organizationId) throw new Error("Set a token and organization ID");

const ship = new OpenshipClient({
  baseUrl: "https://ship.example.com",
  token,
  organizationId,
});

const projects = await ship.projects.list({ page: 1, perPage: 20 });
console.log(projects.data);

export OPENSHIP_URL="https://ship.example.com"
export OPENSHIP_ORGANIZATION_ID="org_123"
# Set OPENSHIP_TOKEN to your personal access token.

curl "$OPENSHIP_URL/api/projects?page=1&perPage=20" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "X-Organization-Id: $OPENSHIP_ORGANIZATION_ID" \
  -H "X-Openship-Scope: fixed"

Example conventions

Resource examples use ship for a configured remote client or native user scope. Replace IDs such as proj_123 with your own. REST examples use the URL and token above; a token's organization binding applies to every request. To pin an organization independently of defaults, include the two scope headers shown above. Older APIs must support fixed scopes.

Named SDK methods unwrap response envelopes where applicable. For example, projects.get(id) returns a project, while its REST endpoint returns { data: project }. IDs may be method arguments in the SDK and URL, query, or body fields in REST; the code tabs show that mapping.

Applications

Networking

Operations

Access and infrastructure

For transport details, see HTTP basics. For errors, providers, and current native/Cloud limits, see SDK errors and compatibility.