Skip to content
Phaset Docs

Integration API Examples

OpenAPI schema

Section titled “OpenAPI schema”

We provide a full OpenAPI schema here.

API endpoint

Section titled “API endpoint”

You define the API endpoint yourself, based on how you expose the API to the world.

Endpoints

Section titled “Endpoints”

Phaset provides several integration endpoints:

  • Records: POST /integration/record/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}
  • Standards: POST /integration/standards/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}
  • Events: POST /integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}
  • Baselines: GET /integration/baselines/{ORG_ID}/{BASELINE_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Timestamps

Section titled “Timestamps”

For all timestamps the required format is the Unix timestamp (10 or 13 digits as a string).

Records

Section titled “Records”

The following is a relatively comprehensive example:

Terminal window
curl -X POST -d '{
  "spec": {
    "name": "Test Component",
    "repo": "https://github.com/my_org/test_component",
    "description": "A test component",
    "lifecycleStage": "development",
    "version": "1.0.0",
    "kind": "service",
    "group": "<random_id>",
    "system": "<random_id>",
    "domain": "<random_id>",
    "dataSensitivity": "internal",
    "businessCriticality": "high",
    "deploymentModel": "public_cloud",
    "sourcingModel": "custom"
  },
  "baseline": {
    "id": "abcd1234"
  },
  "contacts": [
    {
      "email": "[email protected]",
      "relation": "owner"
    }
  ],
  "tags": [
    "test",
    "example"
  ],
  "slo": [
    {
      "title": "Availability",
      "description": "Service availability",
      "type": "availability",
      "target": "99.9%",
      "period": 30
    }
  ],
  "links": [
    {
      "url": "https://example.com",
      "title": "Example",
      "icon": "web"
    }
  ],
  "api": [
    {
      "name": "TestAPI",
      "schemaPath": "/schema/test.json"
    }
  ],
  "dependencies": [
    {
      "target": "abcde12345",
      "description": "A description here",
      "criticality": "medium"
    }
  ],
  "metadata": {
    "createdBy": "test-user"
  }
}' https://api.your_company.cloud/integration/record/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Record Schema Notes

Section titled “Record Schema Notes”

Required fields:

Optional spec fields:

  • spec.description - Component description (max 1500 chars)
  • spec.kind - Type: service, api, component, cots, product, external, other
  • spec.lifecycleStage - Stage: concept, planning, development, testing, production, maintenance, deprecated, retired
  • spec.version - Version string (e.g., “1.0.0”)
  • spec.group - 8-character group ID
  • spec.system - 8-character system ID
  • spec.domain - 8-character domain ID
  • spec.dataSensitivity - Level: public, internal, secret, other
  • spec.businessCriticality - Level: critical, high, medium, low, auxiliary
  • spec.sourcingModel - Model: cots, modified_cots, open_source, custom, outsourced, legacy
  • spec.deploymentModel - Model: onpremises, private_cloud, public_cloud, hybrid_cloud, multi_cloud, edge, saas

Top-level optional fields:

  • contacts - Array of contacts (max 3), each with required email and optional relation
  • baseline - Object with id field referencing a Baseline
  • tags - Array of URL-safe strings (max 5, each max 20 chars)
  • dependencies - Array of dependencies with required target (10-char Record ID), optional description (max 300 chars) and criticality
  • slo - Array of SLOs (max 20), each requires title, description, type, target, period (1-365 days)
  • api - Array of APIs (max 20), each requires name and optional schemaPath (absolute URL)
  • metadata - Object with custom string key-value pairs (max 500 chars per value)
  • links - Array of links (max 20), each requires url, title, and optional icon

Standards

Section titled “Standards”

The input is a StandardLint result which you get by running StandardLint, an open source Node.js package. For the standards check to run and results to be sent, the Baseline connected to the Record will be fetched and used. If one is not defined, the default Baseline will be used.

Please see the StandardLint documentation for more details.

Getting a Baseline Configuration

Section titled “Getting a Baseline Configuration”

Before running standards checks, you can retrieve your Baseline configuration:

Terminal window
curl -X GET \
  https://api.your_company.cloud/integration/baselines/{ORG_ID}/{BASELINE_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

This returns a configuration file that can be used with StandardLint.

Uploading Standards Results

Section titled “Uploading Standards Results”

A call to upload standards results might look like this:

Terminal window
curl -X POST -d '{
  "passes": 20,
  "warnings": 2,
  "failures": 1,
  "results": [
    {
      "message": "Some message",
      "name": "ResultName",
      "path": "filename.md",
      "status": "pass"
    }
  ]
}' https://api.your_company.cloud/integration/standards/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Required fields:

  • passes - Number of passing checks
  • warnings - Number of warnings
  • failures - Number of failures
  • results - Array of result objects, each with:
    • message - Description of the check result
    • name - Name of the check
    • path - Path to the checked file
    • status - One of: pass, warning, failure

Events

Section titled “Events”

All event metrics are sent to the same endpoint: POST /integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Change

Section titled “Change”

The timestamp can be omitted, in which case the current system time will be used.

Terminal window
curl -X POST -d '{
  "event": "change",
  "commitSha": "cf1d3df5ea4373e69d8adc3808e9f8ce23b61360",
  "timestamp": "1732802071"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Deployment

Section titled “Deployment”

The timestamp can be omitted, in which case the current system time will be used.

Terminal window
curl -X POST -d '{
  "event": "deployment",
  "commitSha": "cf1d3df5ea4373e69d8adc3808e9f8ce23b61360"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Required fields:

  • event - Must be "deployment"
  • commitSha - Git commit SHA

Incident opened

Section titled “Incident opened”

This tracks the issue being opened.

Terminal window
curl -X POST -d '{
  "event": "incident-opened",
  "id": "abc123",
  "createdAt": "1732718640"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Required fields:

  • event - Must be "incident-opened"
  • id - Incident identifier
  • createdAt - Unix timestamp

Incident resolved

Section titled “Incident resolved”
Terminal window
curl -X POST -d '{
  "event": "incident-resolved",
  "id": "abc123",
  "createdAt": "1732718640",
  "resolvedAt": "1732718800"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Required fields:

  • event - Must be "incident-resolved"
  • id - Incident identifier
  • createdAt - Unix timestamp when incident was created
  • resolvedAt - Unix timestamp when incident was resolved

Comment

Section titled “Comment”
Terminal window
curl -X POST -d '{
  "event": "comment"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Required fields:

  • event - Must be "comment"

Review approved

Section titled “Review approved”
Terminal window
curl -X POST -d '{
  "event": "review-approved",
  "createdAt": "1732802071",
  "submittedAt": "1733000000"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Required fields:

  • event - Must be "review-approved"

Optional fields:

  • createdAt - Unix timestamp when review was created
  • submittedAt - Unix timestamp when review was submitted

Review changes requested

Section titled “Review changes requested”
Terminal window
curl -X POST -d '{
  "event": "review-changes",
  "createdAt": "1732802071",
  "submittedAt": "1733000000"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Required fields:

  • event - Must be "review-changes"

Optional fields:

  • createdAt - Unix timestamp when review was created
  • submittedAt - Unix timestamp when changes were requested

Pull request opened

Section titled “Pull request opened”
Terminal window
curl -X POST -d '{
  "event": "pr-opened",
  "additions": 5,
  "changedFiles": 3,
  "deletions": 2
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Required fields:

  • event - Must be "pr-opened"

Optional fields:

  • additions - Number of lines added
  • changedFiles - Number of files changed
  • deletions - Number of lines deleted

Pull request closed

Section titled “Pull request closed”
Terminal window
curl -X POST -d '{
  "event": "pr-closed",
  "createdAt": "1732802071",
  "closedAt": "1732809000"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Required fields:

  • event - Must be "pr-closed"

Optional fields:

  • createdAt - Unix timestamp when PR was created
  • closedAt - Unix timestamp when PR was closed

Pull request merged

Section titled “Pull request merged”
Terminal window
curl -X POST -d '{
  "event": "pr-merged",
  "createdAt": "1732802071",
  "mergedAt": "1732809000"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Required fields:

  • event - Must be "pr-merged"

Optional fields:

  • createdAt - Unix timestamp when PR was created
  • mergedAt - Unix timestamp when PR was merged