# Mutations (/api/mutations)



{/* AUTO-GENERATED by scripts/generate-graphql-docs.mjs from @alternatefutures/backend@0.1.2. Do not edit by hand. */}

<Callout type="info">
  Generated from the API server source (@alternatefutures/backend 0.1.2) on every merge. Endpoint
  `https://api.alternatefutures.ai/graphql`, header `Authorization: Bearer <personal access token>`.
  See the [GraphQL API overview](/api) for how to call it. Left out on purpose: provider-specific types, fields and arguments; operations of the retired hosting product (sites, IPFS storage, functions) and admin-only operations.
</Callout>

## Auth - SDK token exchange [#auth---sdk-token-exchange]

### loginWithPersonalAccessToken [#loginwithpersonalaccesstoken]

Exchange a Personal Access Token for a short-lived access token.
Used by the SDK to authenticate subsequent requests.

| Argument | Type                                                                                                                                  | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `data`   | `LoginWithPersonalAccessTokenDataInput!` · [LoginWithPersonalAccessTokenDataInput](/api/inputs#loginwithpersonalaccesstokendatainput) |             |

Returns `String!`.

## Auth [#auth]

### createPersonalAccessToken [#createpersonalaccesstoken]

| Argument    | Type      | Description |
| ----------- | --------- | ----------- |
| `name`      | `String!` |             |
| `expiresAt` | `Date`    |             |

Returns `PersonalAccessTokenCreated!` · [PersonalAccessTokenCreated](/api/objects#personalaccesstokencreated).

### deletePersonalAccessToken [#deletepersonalaccesstoken]

| Argument | Type  | Description |
| -------- | ----- | ----------- |
| `id`     | `ID!` |             |

Returns `Boolean!`.

## Projects [#projects]

### createProject [#createproject]

| Argument | Type                                                                                     | Description |
| -------- | ---------------------------------------------------------------------------------------- | ----------- |
| `data`   | `CreateProjectDataInput!` · [CreateProjectDataInput](/api/inputs#createprojectdatainput) |             |

Returns `Project!` · [Project](/api/objects#project).

### updateProject [#updateproject]

| Argument | Type                                                                                     | Description |
| -------- | ---------------------------------------------------------------------------------------- | ----------- |
| `id`     | `ID!`                                                                                    |             |
| `data`   | `UpdateProjectDataInput!` · [UpdateProjectDataInput](/api/inputs#updateprojectdatainput) |             |

Returns `Project!` · [Project](/api/objects#project).

### deleteProject [#deleteproject]

| Argument | Type  | Description |
| -------- | ----- | ----------- |
| `id`     | `ID!` |             |

Returns `Boolean!`.

### projectChatSession [#projectchatsession]

Mint a single-use join ticket (plus room id, relay URL and room secret)
for a project's chat. Requires project access; organization projects
only. Relay-blind, not end-to-end: the platform can read project chat.

| Argument    | Type  | Description |
| ----------- | ----- | ----------- |
| `projectId` | `ID!` |             |

Returns `ProjectChatSession!` · [ProjectChatSession](/api/objects#projectchatsession).

### publicChatTicket [#publicchatticket]

Mint a single-use join ticket for the hosted public chat. Requires only an
authenticated caller: no org or project check. The ticket is NOT bound to
a room: the platform never learns which public rooms exist or who is in
them, only that this user opened chat.

Returns `PublicChatTicket!` · [PublicChatTicket](/api/objects#publicchatticket).

## Services [#services]

### createService [#createservice]

| Argument | Type                                                                         | Description |
| -------- | ---------------------------------------------------------------------------- | ----------- |
| `input`  | `CreateServiceInput!` · [CreateServiceInput](/api/inputs#createserviceinput) |             |

Returns `Service!` · [Service](/api/objects#service).

### updateService [#updateservice]

| Argument    | Type                                                                         | Description |
| ----------- | ---------------------------------------------------------------------------- | ----------- |
| `serviceId` | `ID!`                                                                        |             |
| `input`     | `UpdateServiceInput!` · [UpdateServiceInput](/api/inputs#updateserviceinput) |             |

Returns `Service!` · [Service](/api/objects#service).

### updateServicePriority [#updateservicepriority]

| Argument           | Type   | Description |
| ------------------ | ------ | ----------- |
| `serviceId`        | `ID!`  |             |
| `shutdownPriority` | `Int!` |             |

Returns `Service!` · [Service](/api/objects#service).

### deleteService [#deleteservice]

| Argument | Type  | Description |
| -------- | ----- | ----------- |
| `id`     | `ID!` |             |

Returns `Service!` · [Service](/api/objects#service).

## Attestation registry (org allowlist; AF hosts, org authors) [#attestation-registry-org-allowlist-af-hosts-org-authors]

### addAttestationMeasurement [#addattestationmeasurement]

Bless a build measurement (compose\_hash) in the active org's allowlist.

| Argument | Type                                                                                                             | Description |
| -------- | ---------------------------------------------------------------------------------------------------------------- | ----------- |
| `input`  | `AddAttestationMeasurementInput!` · [AddAttestationMeasurementInput](/api/inputs#addattestationmeasurementinput) |             |

Returns `AttestationMeasurement!` · [AttestationMeasurement](/api/objects#attestationmeasurement).

### revokeAttestationMeasurement [#revokeattestationmeasurement]

Revoke a blessed measurement. Idempotent; revocation retires every identity minted from it.

| Argument | Type  | Description |
| -------- | ----- | ----------- |
| `id`     | `ID!` |             |

Returns `AttestationMeasurement!` · [AttestationMeasurement](/api/objects#attestationmeasurement).

### registerAttestedIdentity [#registerattestedidentity]

Verify a server's quote (Intel DCAP roots, in-process) and record its
identity. Requires the quote's measurement to be ACTIVE in the active
org's allowlist and the quote's report\_data to bind the pubkey.

| Argument | Type                                                                                                          | Description |
| -------- | ------------------------------------------------------------------------------------------------------------- | ----------- |
| `input`  | `RegisterAttestedIdentityInput!` · [RegisterAttestedIdentityInput](/api/inputs#registerattestedidentityinput) |             |

Returns `AttestedIdentity!` · [AttestedIdentity](/api/objects#attestedidentity).

## Agent chat [#agent-chat]

### createAgent [#createagent]

| Argument | Type                                                                   | Description |
| -------- | ---------------------------------------------------------------------- | ----------- |
| `input`  | `CreateAgentInput!` · [CreateAgentInput](/api/inputs#createagentinput) |             |

Returns `Agent!` · [Agent](/api/objects#agent).

### createChat [#createchat]

| Argument | Type                                                                | Description |
| -------- | ------------------------------------------------------------------- | ----------- |
| `input`  | `CreateChatInput!` · [CreateChatInput](/api/inputs#createchatinput) |             |

Returns `Chat!` · [Chat](/api/objects#chat).

### sendMessage [#sendmessage]

| Argument | Type                                                                   | Description |
| -------- | ---------------------------------------------------------------------- | ----------- |
| `input`  | `SendMessageInput!` · [SendMessageInput](/api/inputs#sendmessageinput) |             |

Returns `Message!` · [Message](/api/objects#message).

### deleteChat [#deletechat]

| Argument | Type  | Description |
| -------- | ----- | ----------- |
| `id`     | `ID!` |             |

Returns `Boolean!`.

## Observability settings [#observability-settings]

### updateObservabilitySettings [#updateobservabilitysettings]

| Argument    | Type                                                                                                                   | Description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------- | ----------- |
| `projectId` | `ID!`                                                                                                                  |             |
| `input`     | `UpdateObservabilitySettingsInput!` · [UpdateObservabilitySettingsInput](/api/inputs#updateobservabilitysettingsinput) |             |

Returns `ObservabilitySettings!` · [ObservabilitySettings](/api/objects#observabilitysettings).

## Templates [#templates]

### deployFromTemplate [#deployfromtemplate]

| Argument | Type                                                                                        | Description |
| -------- | ------------------------------------------------------------------------------------------- | ----------- |
| `input`  | `DeployFromTemplateInput!` · [DeployFromTemplateInput](/api/inputs#deployfromtemplateinput) |             |

Returns a deployment object for the service's compute tier (provider-specific, not documented here). †

### deployCompositeTemplate [#deploycompositetemplate]

| Argument | Type                                                                                                       | Description |
| -------- | ---------------------------------------------------------------------------------------------------------- | ----------- |
| `input`  | `DeployCompositeTemplateInput!` · [DeployCompositeTemplateInput](/api/inputs#deploycompositetemplateinput) |             |

Returns `CompositeDeploymentResult!` · [CompositeDeploymentResult](/api/objects#compositedeploymentresult).

## Service environment variables [#service-environment-variables]

### setServiceEnvVar [#setserviceenvvar]

| Argument    | Type      | Description |
| ----------- | --------- | ----------- |
| `serviceId` | `ID!`     |             |
| `key`       | `String!` |             |
| `value`     | `String!` |             |
| `secret`    | `Boolean` |             |

Returns `ServiceEnvVar!` · [ServiceEnvVar](/api/objects#serviceenvvar).

### deleteServiceEnvVar [#deleteserviceenvvar]

| Argument    | Type      | Description |
| ----------- | --------- | ----------- |
| `serviceId` | `ID!`     |             |
| `key`       | `String!` |             |

Returns `Boolean!`.

### bulkSetServiceEnvVars [#bulksetserviceenvvars]

| Argument    | Type                                                       | Description |
| ----------- | ---------------------------------------------------------- | ----------- |
| `serviceId` | `ID!`                                                      |             |
| `vars`      | `[EnvVarInput!]!` · [EnvVarInput](/api/inputs#envvarinput) |             |

Returns `[ServiceEnvVar!]!` · [ServiceEnvVar](/api/objects#serviceenvvar).

### revealServiceEnvVar [#revealserviceenvvar]

| Argument    | Type      | Description |
| ----------- | --------- | ----------- |
| `serviceId` | `ID!`     |             |
| `key`       | `String!` |             |

Returns `String!`.

## Service port configuration [#service-port-configuration]

### setServicePort [#setserviceport]

| Argument        | Type     | Description |
| --------------- | -------- | ----------- |
| `serviceId`     | `ID!`    |             |
| `containerPort` | `Int!`   |             |
| `publicPort`    | `Int`    |             |
| `protocol`      | `String` |             |

Returns `ServicePort!` · [ServicePort](/api/objects#serviceport).

### deleteServicePort [#deleteserviceport]

| Argument        | Type   | Description |
| --------------- | ------ | ----------- |
| `serviceId`     | `ID!`  |             |
| `containerPort` | `Int!` |             |

Returns `Boolean!`.

## Service linking [#service-linking]

### linkServices [#linkservices]

| Argument          | Type     | Description |
| ----------------- | -------- | ----------- |
| `sourceServiceId` | `ID!`    |             |
| `targetServiceId` | `ID!`    |             |
| `alias`           | `String` |             |

Returns `ServiceLink!` · [ServiceLink](/api/objects#servicelink).

### unlinkServices [#unlinkservices]

| Argument          | Type  | Description |
| ----------------- | ----- | ----------- |
| `sourceServiceId` | `ID!` |             |
| `targetServiceId` | `ID!` |             |

Returns `Boolean!`.

## Deployment file access (files tab) [#deployment-file-access-files-tab]

### writeServiceFile [#writeservicefile]

| Argument    | Type      | Description |
| ----------- | --------- | ----------- |
| `serviceId` | `ID!`     |             |
| `path`      | `String!` |             |
| `content`   | `String!` |             |

Returns `ServiceFileWriteResult!` · [ServiceFileWriteResult](/api/objects#servicefilewriteresult).

### createServiceDirectory [#createservicedirectory]

| Argument    | Type      | Description |
| ----------- | --------- | ----------- |
| `serviceId` | `ID!`     |             |
| `path`      | `String!` |             |

Returns `Boolean!`.

### renameServiceFile [#renameservicefile]

| Argument    | Type      | Description |
| ----------- | --------- | ----------- |
| `serviceId` | `ID!`     |             |
| `fromPath`  | `String!` |             |
| `toPath`    | `String!` |             |

Returns `Boolean!`.

### deleteServiceFile [#deleteservicefile]

| Argument    | Type      | Description |
| ----------- | --------- | ----------- |
| `serviceId` | `ID!`     |             |
| `path`      | `String!` |             |

Returns `Boolean!`.

## Feedback [#feedback]

### submitFeedback [#submitfeedback]

| Argument | Type                                                                            | Description |
| -------- | ------------------------------------------------------------------------------- | ----------- |
| `input`  | `SubmitFeedbackInput!` · [SubmitFeedbackInput](/api/inputs#submitfeedbackinput) |             |

Returns `FeedbackReport!` · [FeedbackReport](/api/objects#feedbackreport).

## GitHub deploy [#github-deploy]

### beginGithubInstallationClaim [#begingithubinstallationclaim]

Begin a one-use GitHub user-authorization proof bound to the caller, AF
organization, and exact installation id returned by GitHub's setup URL.

| Argument         | Type      | Description |
| ---------------- | --------- | ----------- |
| `installationId` | `String!` |             |
| `orgId`          | `ID`      |             |

Returns `GithubInstallationClaim!` · [GithubInstallationClaim](/api/objects#githubinstallationclaim).

### syncGithubInstallation [#syncgithubinstallation]

Create or grant an installation only after exchanging a GitHub user OAuth
code and proving that user can access the exact App installation.

| Argument | Type      | Description |
| -------- | --------- | ----------- |
| `state`  | `String!` |             |
| `code`   | `String!` |             |

Returns `GithubInstallationSyncResult!` · [GithubInstallationSyncResult](/api/objects#githubinstallationsyncresult).

### refreshGithubInstallations [#refreshgithubinstallations]

Live-pull all accessible App installations from GitHub into the local DB and return them.
Slow path: UI uses this only on explicit Refresh / post-install.

| Argument | Type | Description |
| -------- | ---- | ----------- |
| `orgId`  | `ID` |             |

Returns `[GithubInstallation!]!` · [GithubInstallation](/api/objects#githubinstallation).

### uninstallGithubInstallation [#uninstallgithubinstallation]

Remove only this AF organization's installation grant and detach its
services. GitHub-wide uninstall remains an installation-admin action on
github.com and is reconciled by the signed deletion webhook.

| Argument         | Type  | Description |
| ---------------- | ----- | ----------- |
| `installationId` | `ID!` |             |
| `orgId`          | `ID`  |             |

Returns `Boolean!`.

### createGithubService [#creategithubservice]

| Argument | Type                                                                                           | Description |
| -------- | ---------------------------------------------------------------------------------------------- | ----------- |
| `input`  | `CreateGithubServiceInput!` · [CreateGithubServiceInput](/api/inputs#creategithubserviceinput) |             |

Returns `Service!` · [Service](/api/objects#service).

### connectGithubRepo [#connectgithubrepo]

| Argument | Type                                                                                     | Description |
| -------- | ---------------------------------------------------------------------------------------- | ----------- |
| `input`  | `ConnectGithubRepoInput!` · [ConnectGithubRepoInput](/api/inputs#connectgithubrepoinput) |             |

Returns `Service!` · [Service](/api/objects#service).

### redeployGithubService [#redeploygithubservice]

Trigger a new build. With no sha, builds the tip of the tracked branch (default behaviour, used by top-level Rebuild). With a sha (7-40 char hex commit SHA), rebuilds that exact commit: used by the per-row rebuild button in build history.

| Argument    | Type     | Description |
| ----------- | -------- | ----------- |
| `serviceId` | `ID!`    |             |
| `sha`       | `String` |             |

Returns `BuildJob!` · [BuildJob](/api/objects#buildjob).

† Some fields, arguments or return types are omitted from this page: provider-specific ones, or ones that belong to retired or admin-only surfaces.