Faros Webhooks API
Inbound webhook endpoints that let source systems push events into Faros. Each webhook definition provides a unique URL of the form POST /webhooks/{webhook_id}/events for delivering events to the platform.
OpenAPI Specification
openapi: 3.0.1
info:
title: Faros AI API
description: >-
REST surface for the Faros AI engineering-operations intelligence platform.
Covers account/identity, graph management, event and data ingestion,
inbound webhooks, and the GraphQL query endpoint over the Faros canonical
model. All requests are authenticated with a Faros API key passed in the
Authorization header. Endpoint paths are modeled from the public Faros
documentation, faros-js-client, and faros-events-cli; verify against the
Faros API reference for exact request/response schemas.
termsOfService: https://www.faros.ai/legal/terms-of-service
contact:
name: Faros AI Support
email: support@faros.ai
url: https://docs.faros.ai
version: '1.0'
servers:
- url: https://prod.api.faros.ai
description: Faros production API
security:
- apiKey: []
paths:
/users/me:
get:
operationId: getCurrentUser
tags:
- Account
summary: Get the current authenticated user.
description: >-
Returns the identity and account context associated with the API key
used in the Authorization header.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
description: Unauthorized
/accounts:
get:
operationId: listAccounts
tags:
- Account
summary: List accounts accessible to the caller.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
accounts:
type: array
items:
$ref: '#/components/schemas/Account'
/graphs:
get:
operationId: listGraphs
tags:
- Graphs
summary: List graphs in the account.
description: >-
Lists the named graphs available to the account. The canonical graph
is typically named "default".
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
graphs:
type: array
items:
$ref: '#/components/schemas/Graph'
/graphs/{graph}:
parameters:
- $ref: '#/components/parameters/graph'
get:
operationId: getGraph
tags:
- Graphs
summary: Get a single graph.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Graph'
put:
operationId: createOrUpdateGraph
tags:
- Graphs
summary: Create or update a graph.
responses:
'200':
description: OK
delete:
operationId: deleteGraph
tags:
- Graphs
summary: Delete a graph.
responses:
'200':
description: OK
/graphs/{graph}/graphql:
parameters:
- $ref: '#/components/parameters/graph'
post:
operationId: queryGraph
tags:
- GraphQL
summary: Execute a GraphQL query or mutation against a graph.
description: >-
Hasura-backed GraphQL endpoint over the Faros canonical model. Accepts
a standard GraphQL request body (query, variables, operationName) and
returns a GraphQL response. Used to query SDLC entities and to write
data via GraphQL mutations.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLResponse'
/graphs/{graph}/models:
parameters:
- $ref: '#/components/parameters/graph'
get:
operationId: listModels
tags:
- Ingestion
summary: List canonical models available in the graph.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
models:
type: array
items:
type: string
post:
operationId: writeModelRecords
tags:
- Ingestion
summary: Write canonical model records into the graph.
description: >-
Ingests records that conform to the Faros canonical model (for example
cicd_Deployment, cicd_Build, vcs_PullRequest, tms_Task). Records are
upserted into the graph and reconciled against existing entities.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModelRecordBatch'
responses:
'200':
description: OK
/graphs/{graph}/revisions:
parameters:
- $ref: '#/components/parameters/graph'
post:
operationId: createRevision
tags:
- Ingestion
summary: Create an ingestion revision.
description: >-
Opens a revision that groups a batch of model writes for the graph,
used to coordinate and track an ingestion run.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Revision'
/graphs/{graph}/events:
parameters:
- $ref: '#/components/parameters/graph'
post:
operationId: sendEvents
tags:
- Events
summary: Report CI/CD and test events to a graph.
description: >-
Reports CI (build), CD (deployment), and TestExecution events into the
graph. This is the surface used by faros-events-cli and the Faros CI/CD
GitHub Action to power DORA and delivery metrics.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EventBatch'
responses:
'200':
description: OK
/webhooks/{webhook_id}/events:
parameters:
- name: webhook_id
in: path
required: true
description: The id from the webhook definition created in the Faros app.
schema:
type: string
post:
operationId: deliverWebhookEvents
tags:
- Webhooks
summary: Deliver events to a configured webhook.
description: >-
Inbound webhook endpoint. Each webhook definition in the Faros
application provides a unique URL of this form; source systems POST
their event payloads here for ingestion.
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: OK
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: Authorization
description: >-
Faros API key created in the Faros application under
Settings -> API Keys. Passed directly in the Authorization header.
parameters:
graph:
name: graph
in: path
required: true
description: The name of the graph, e.g. "default".
schema:
type: string
schemas:
User:
type: object
properties:
id:
type: string
email:
type: string
tenantId:
type: string
Account:
type: object
properties:
accountId:
type: string
name:
type: string
type:
type: string
Graph:
type: object
properties:
name:
type: string
tenantId:
type: string
GraphQLRequest:
type: object
required:
- query
properties:
query:
type: string
variables:
type: object
additionalProperties: true
operationName:
type: string
GraphQLResponse:
type: object
properties:
data:
type: object
additionalProperties: true
errors:
type: array
items:
type: object
additionalProperties: true
ModelRecordBatch:
type: object
properties:
origin:
type: string
description: Source identifier for the ingested records.
entries:
type: array
items:
type: object
additionalProperties: true
description: >-
A canonical model record keyed by entity type, e.g.
{ "cicd_Deployment": { ... } }.
Revision:
type: object
properties:
revision:
type: string
status:
type: string
EventBatch:
type: object
properties:
origin:
type: string
events:
type: array
items:
type: object
additionalProperties: true
description: A CI, CD, or TestExecution event payload.