# Faros AI GraphQL API

Faros AI exposes a native, Hasura-powered GraphQL API over its connected canonical model for the whole software development lifecycle (50+ entities, from tasks to deployments). Any GraphQL client can query the data.

**Endpoint:** `POST https://prod.api.faros.ai/graphs/{graph}/graphql` (graph is typically `default`)
**Authentication:** Faros API key in the `Authorization` header
**Documentation:** https://docs.faros.ai/docs/querying-data

- Reference: https://docs.faros.ai/docs/using-graphiql-application-to-query-data
- Schema (representative SDL): [`faros-schema.graphql`](./faros-schema.graphql)
- Community Edition: https://github.com/faros-ai/faros-community-edition

> The schema in [`faros-schema.graphql`](./faros-schema.graphql) is a **representative** SDL of the Faros canonical model and Hasura query surface. The live, tenant-specific schema is generated by Hasura and is richer (auto-generated filter/aggregate/order-by arguments per table). Use GraphiQL against your own graph for the authoritative schema.

---

## Canonical model namespaces

Faros organizes its canonical entities into SDLC namespaces. Common prefixes include:

| Namespace | Domain | Example entities |
|-----------|--------|------------------|
| `vcs_` | Version control | `vcs_Repository`, `vcs_PullRequest`, `vcs_Commit`, `vcs_Branch`, `vcs_User` |
| `cicd_` | CI/CD & delivery | `cicd_Build`, `cicd_Deployment`, `cicd_Pipeline`, `cicd_Artifact`, `cicd_Release` |
| `tms_` | Task management | `tms_Task`, `tms_Project`, `tms_Sprint`, `tms_Epic`, `tms_TaskBoard` |
| `qa_` | Quality / testing | `qa_TestExecution`, `qa_TestCase`, `qa_TestSuite` |
| `ims_` | Incident management | `ims_Incident`, `ims_IncidentEvent`, `ims_IncidentApplicationImpact` |
| `compute_` | Compute / apps | `compute_Application`, `compute_Deployment` |
| `org_` | Organization | `org_Team`, `org_TeamMembership`, `org_Employee` |
| `faros_` | Platform meta | `faros_Tag`, `faros_MetricDefinition`, `faros_MetricValue` |

---

## Query examples

### List pull requests with their author and reviews

```graphql
query {
  vcs_PullRequest(limit: 50, order_by: { createdAt: desc }) {
    number
    title
    state
    createdAt
    mergedAt
    author { name }
    reviews {
      state
      reviewer { name }
    }
  }
}
```

### Deployments for DORA delivery metrics

```graphql
query {
  cicd_Deployment(
    where: { status: { category: { _eq: "Success" } } }
    order_by: { endedAt: desc }
    limit: 100
  ) {
    uid
    status { category detail }
    startedAt
    endedAt
    application { name }
    build { uid }
  }
}
```

### Open incidents by severity

```graphql
query {
  ims_Incident(where: { resolvedAt: { _is_null: true } }) {
    uid
    title
    severity { category }
    createdAt
    applicationImpacts {
      application { name }
    }
  }
}
```

### Tasks by project and status

```graphql
query {
  tms_Task(where: { project: { name: { _eq: "Platform" } } }, limit: 100) {
    uid
    name
    status { category }
    type { category }
    assignee { name }
  }
}
```

### Aggregate build counts (Hasura aggregate)

```graphql
query {
  cicd_Build_aggregate {
    aggregate {
      count
    }
  }
}
```

### Write data via a GraphQL mutation (upsert)

```graphql
mutation {
  insert_cicd_Deployment_one(
    object: {
      uid: "deploy-123"
      source: "MyPipeline"
      status: { category: "Success" }
    }
    on_conflict: { constraint: cicd_Deployment_pkey, update_columns: [status] }
  ) {
    id
  }
}
```