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"

# Search entities with Port-style rules (+ free text and sort)
# sort.property: $title / $identifier / $createdAt / $updatedAt, or any scalar blueprint property
# (unknown $meta names return 422)
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"rules":[{"property":"env","operator":"=","value":"prod"},{"property":"$team","operator":"containsAny","value":["platform"]}],"combinator":"and","search":"eu","sort":{"property":"tier","order":"DESC"},"limit":50}' \
  "https://<idp>/api/v1/blueprints/cluster/entities/search"

Workflows & runs

# List / create workflows (optional ?category=Deployment filter)
curl -H "Authorization: Bearer $TOKEN" "https://<idp>/api/v1/workflows"
curl -H "Authorization: Bearer $TOKEN" "https://<idp>/api/v1/workflows?category=Deployment"
# Distinct categories in use ("Generic" is always first)
curl -H "Authorization: Bearer $TOKEN" "https://<idp>/api/v1/workflows/categories"
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; a step may carry "loop": {"items": "<jq>", "maxConcurrency": n})
curl -H "Authorization: Bearer $TOKEN" "https://<idp>/api/v1/workflows/deploy-stack-github"

# Resolve the dynamic parts of a workflow form (visible / disabled / enum / dataset / required)
# for the current values — see Advanced Form Configuration
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"form":{"environment":"prod"},"entity":"svc-orders","includeDefaults":true}' \
  "https://<idp>/api/v1/workflows/deploy-stack-github/form/evaluate"

# 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"