Integration API Examples

OpenAPI schema

API endpoint

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

Endpoints

Phaset provides several integration endpoints:

Purpose	Method	Endpoint
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

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

Records

The following is a relatively comprehensive example:

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

Required Fields

Field	Description
`spec.repo`	Repository link (e.g., `https://github.com/my_org/my_repo`)
`spec.name`	Name of the component

Optional Spec Fields

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

Top-Level Optional Fields

Field	Type	Constraints	Description
`contacts`	Array	Max 3 items	Each contact requires `email`, optional `relation`
`baseline`	Object	-	Object with `id` field referencing a Baseline
`tags`	Array	Max 5, each max 20 chars	URL-safe strings
`dependencies`	Array	-	Requires `target` (10-char Record ID), optional `description` (max 300 chars) and `criticality`
`slo`	Array	Max 20 items	Requires `title`, `description`, `type`, `target`, `period` (1-365 days)
`api`	Array	Max 20 items	Requires `name`, optional `schemaPath` (absolute URL)
`metadata`	Object	Max 500 chars per value	Custom string key-value pairs
`links`	Array	Max 20 items	Requires `url`, `title`, optional `icon`

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

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

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

A call to upload standards results might look like this:

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}

Standards Schema

Field	Type	Description
`passes`	Number	Number of passing checks
`warnings`	Number	Number of warnings
`failures`	Number	Number of failures
`results`	Array	Array of result objects (see below)

Result Object Fields:

Field	Type	Description
`message`	String	Description of the check result
`name`	String	Name of the check
`path`	String	Path to the checked file
`status`	Enum	One of: `pass`, `warning`, `failure`

Events

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

Change

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

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

Field	Required	Type	Description
`event`	✓	String	Must be `"change"`
`commitSha`	✓	String	Git commit SHA
`timestamp`	-	String	Unix timestamp (defaults to current time if omitted)

Deployment

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

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

Field	Required	Type	Description
`event`	✓	String	Must be `"deployment"`
`commitSha`	✓	String	Git commit SHA

Incident opened

This tracks the issue being opened.

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

Field	Required	Type	Description
`event`	✓	String	Must be `"incident-opened"`
`id`	✓	String	Incident identifier
`createdAt`	✓	String	Unix timestamp when incident was created

Incident resolved

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}

Field	Required	Type	Description
`event`	✓	String	Must be `"incident-resolved"`
`id`	✓	String	Incident identifier
`createdAt`	✓	String	Unix timestamp when incident was created
`resolvedAt`	✓	String	Unix timestamp when incident was resolved

Comment

curl -X POST -d '{
  "event": "comment"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Field	Required	Type	Description
`event`	✓	String	Must be `"comment"`

Review approved

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

Field	Required	Type	Description
`event`	✓	String	Must be `"review-approved"`
`createdAt`	-	String	Unix timestamp when review was created
`submittedAt`	-	String	Unix timestamp when review was submitted

Review changes requested

curl -X POST -d '{
  "event": "review-changes",
  "createdAt": "1732802071",
  "submittedAt": "1733000000"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Field	Required	Type	Description
`event`	✓	String	Must be `"review-changes"`
`createdAt`	-	String	Unix timestamp when review was created
`submittedAt`	-	String	Unix timestamp when changes were requested

Pull request opened

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}

Field	Required	Type	Description
`event`	✓	String	Must be `"pr-opened"`
`additions`	-	Number	Number of lines added
`changedFiles`	-	Number	Number of files changed
`deletions`	-	Number	Number of lines deleted

Pull request closed

curl -X POST -d '{
  "event": "pr-closed",
  "createdAt": "1732802071",
  "closedAt": "1732809000"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Field	Required	Type	Description
`event`	✓	String	Must be `"pr-closed"`
`createdAt`	-	String	Unix timestamp when PR was created
`closedAt`	-	String	Unix timestamp when PR was closed

Pull request merged

curl -X POST -d '{
  "event": "pr-merged",
  "createdAt": "1732802071",
  "mergedAt": "1732809000"
}' https://api.your_company.cloud/integration/event/{ORG_ID}/{RECORD_ID}/{WEBHOOK_TOKEN}

Field	Required	Type	Description
`event`	✓	String	Must be `"pr-merged"`
`createdAt`	-	String	Unix timestamp when PR was created
`mergedAt`	-	String	Unix timestamp when PR was merged