API Quick Reference

The endpoints used throughout this tutorial. The API is Port-compatible: paths exist both as /api/v1/... (UI-style, with Authorization: Bearer <user JWT> + x-organization-id header) and /v1/... (integration-style, with a service-account token).

Authentication

Service account token (used by CI pipelines and Ocean):

TOKEN=$(curl -s -X POST "https://<idp>/v1/auth/access_token" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"pa_...","clientSecret":"..."}' | jq -r .accessToken)

User token (browser sessions): stored in the browser as idp_auth_token after OAuth login; requests also send x-organization-id.

Blueprints & entities

# List blueprints
curl -H "Authorization: Bearer $TOKEN" "https://<idp>/api/v1/blueprints"

# Create a blueprint
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d @blueprint.json "https://<idp>/api/v1/blueprints"

# List entities of a blueprint
curl -H "Authorization: Bearer $TOKEN" \
  "https://<idp>/api/v1/blueprints/deployment/entities"

Workflows & runs

# List / create workflows
curl -H "Authorization: Bearer $TOKEN" "https://<idp>/api/v1/workflows"
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d @workflow.json "https://<idp>/api/v1/workflows"

# Get one workflow (full definition incl. steps)
curl -H "Authorization: Bearer $TOKEN" "https://<idp>/api/v1/workflows/deploy-stack-github"

# Report a step result from an external pipeline (the deploy.yml callback)
curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"SUCCESS","statusLabel":"reported by callback","externalRunId":"12345"}' \
  "https://<idp>/v1/actions/runs/<sr_step_run_id>"

Integrations (data sources)

# List data sources
curl -H "Authorization: Bearer $TOKEN" "https://<idp>/api/v1/integration"

# Read / update a mapping
curl -H "Authorization: Bearer $TOKEN" "https://<idp>/v1/integration/my-github-ocean-integration"
curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"config":{"resources":[...]}}' \
  "https://<idp>/v1/integration/my-github-ocean-integration"

Webhooks (inbound)

Endpoint	Sender
/api/v1/github/webhook	GitHub App (workflow run events; signed with the webhook secret)
/api/v1/gitlab/webhook	GitLab pipeline webhooks (validated with GITLAB_WEBHOOK_SECRET)

GitHub App setup

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"installationId": 146607536}' "https://<idp>/api/v1/github/setup"