Writer connections

Connect the credentials nima writes with (the GitHub writer app, the Jira writer and the Linear writer) and read their status.

A writer connection is the credential nima uses when it writes into a tool on your behalf: a comment on a pull request, a reply on a Jira ticket, a reply on a Linear issue. It is separate from the read-only connection that brings evidence in. Connecting a writer does not make nima send anything. Jira and Linear replies go only through outbound actions: the policy checks, an approval card unless you opened auto, and the on-behalf-of footer. The GitHub writer is what agent operations publish through (pull request comments and draft pull requests), and only after an owner or admin turns GitHub publishing on.

Writer connections are on for every workspace to connect and inspect. Jira replies also need outbound actions, which are off until a workspace owner or admin turns them on: set dispatchEnabled with PATCH /organizations/settings from a signed-in owner or admin session (see Workspace settings), or ask the nima team. There is no admin-panel control for it. Linear replies are not available yet: enabling the Linear writer does not make nima comment on Linear (see Linear writer). GitHub publishing does not depend on dispatchEnabled. It is its own opt-in: Turn GitHub publishing on or off.

Writer connection routes

Method	Path	Scope	MCP tool
`GET`	`/v1/github-writer/app/install`	`integrations:write`	`get_github_writer_install_url`
`GET`	`/v1/github-writer/app/status`	`integrations:write`	`get_github_publishing_status`
`GET`	`/v1/github-writer/app/callback`	none (public)	none
`PATCH`	`/v1/github-writer/publishing`	`integrations:write`	`set_github_publishing`
`DELETE`	`/v1/github-writer/app/installation`	`integrations:write`	`disconnect_github_writer`
`POST`	`/v1/integrations/jira/writer`	`integrations:write`	none
`GET`	`/v1/integrations/jira/writer`	`integrations:write`	none
`POST`	`/v1/integrations/jira/writer/mcp`	`integrations:write`	`connect_jira_writer`
`POST`	`/v1/integrations/linear/writer`	`integrations:write`	`connect_linear_writer`
`GET`	`/v1/integrations/linear/writer`	`integrations:write`	none

Paths are relative to https://api.getnima.io. The GitHub writer tools are documented on operation tools; connect_jira_writer and connect_linear_writer are on outbound tools.

Who can call the writer routes

Every writer route except the GitHub callback needs the integrations:write scope and a caller who is currently a workspace owner or admin. A member gets 403 INSUFFICIENT_PERMISSIONS, even with the scope.

integrations:write is not on the OAuth consent screen and cannot be picked in Settings or POST /v1/api-keys. An owner or admin gets a key that carries it from Slack: run /nima mcp-key integrations, press Confirm (or tell @nima confirm <code> in the same channel within 5 minutes), and nima shows a 30-day key once. That key can manage integrations, GitHub publishing consent and hosted compute settings, so keep it private and revoke it with /nima mcp-key revoke <key-id> when the setup is done. See Scopes and permissions.

A signed-in owner or admin session, the one the admin panel uses, can also call these routes. Error shapes are in Errors.

GitHub writer app

The GitHub writer is a second, optional GitHub App. The GitHub App you already installed stays read-only. The writer asks for contents: write and pull_requests: write. It is what lets nima publish to GitHub: today, the pull request comments and draft pull requests that agent operations publish. Enabling checks pull_requests: write.

Installing the writer never turns publishing on. The order is install, then enable, and enabling is a separate explicit call.

Get the GitHub writer install URL

GET/v1/github-writer/app/install

scopeintegrations:writeMCP toolget_github_writer_install_url

Returns the URL where an admin installs the writer App on GitHub. The URL carries a signed state that is valid for 10 minutes and works once.

The workspace needs an active read-only GitHub integration first. The writer must later be installed on the same GitHub account as that integration.

urlstring

https://github.com/apps/<writer-slug>/installations/new?state=.... Open it in a browser signed in to GitHub as an account that can install apps.

Status	Meaning
`403` `INSUFFICIENT_PERMISSIONS`	No active read-only GitHub integration, or it is suspended: "Connect an active read-only GitHub integration first".
`503`	The GitHub writer is not configured on this deployment. Retryable; ask the nima team.

GitHub writer install callback

GET/v1/github-writer/app/callback

GitHub redirects the browser here after the install. You do not call it. It is public, and the signed state from the install URL is its only credential.

installation_idstringrequired

The numeric installation id GitHub appends.

statestringrequired

The state from the install URL. It is single-use and expires after 10 minutes.

The call links the writer installation to the workspace and answers {"connected": true, "enabled": false}. It always leaves publishing off, also when the workspace reconnects a writer it had before.

Status	Meaning
`400`	The state is invalid, expired or already used: start again from the install URL.
`403`	The writer is installed on a different GitHub account than the read-only integration, or the read-only integration is suspended.
`409`	This writer installation is already linked to another workspace, or the binding changed while you installed. Start a new install flow.
`503`	The GitHub writer is not configured on this deployment.

Get GitHub writer status

GET/v1/github-writer/app/status

scopeintegrations:writeMCP toolget_github_publishing_status

Reads whether the writer is configured, connected and enabled for this workspace. It reads nima's stored binding. Live repository access is checked again each time something publishes.

configuredboolean

false when this deployment has no writer App. Nothing else can work then.

connectedboolean

A writer installation is linked to the workspace.

enabledboolean

Publishing is on. Always false when configured is false.

installationIdstring | null

The GitHub installation id of the writer, or null.

Turn GitHub publishing on or off

PATCH/v1/github-writer/publishing

scopeintegrations:writeMCP toolset_github_publishing

Turns GitHub publishing on or off for the workspace. Enable it only when a person explicitly asks for it. This consent is independent of the consent for hosted compute.

enabledbooleanrequired

true permits publishing, false opts out. Disabling blocks later publications. One that is already running may finish.

Enabling checks that a writer is connected, that both GitHub installations are active and belong to the same account, and that the writer still holds pull_requests: write. Any failed check answers 403 INSUFFICIENT_PERMISSIONS with the reason in the message. A 409 means the binding changed under you: read the status and retry. Returns the same object as status.

Disconnect the GitHub writer

DELETE/v1/github-writer/app/installation

scopeintegrations:writeMCP tooldisconnect_github_writer

Removes nima's link to the writer App and turns publishing off. The read-only GitHub integration and the compute settings stay as they are. The route is idempotent.

It does not uninstall the App on GitHub. An admin removes it there too, under the GitHub account's installed apps.

The same install, status, enable, disable and disconnect steps run from Slack with /nima github-writer status|install|enable|disable|disconnect. Changes there wait for a Confirm press.

Jira writer

The Jira writer is the identity nima posts Jira comments as. There are two modes, and the mode decides who a comment appears to come from.

Mode	Comments appear as	Approval
`service_account` (preferred)	A dedicated Atlassian account you create for nima, for example one named "nima"	`ask` by default; `auto` only under an `auto` action policy in a project asserted internal, for a member asker
`connector_fallback`	The person who connected Jira	Every reply waits for approval, and cannot be made automatic. Needs comment scopes the normal Jira connection does not grant today

Jira must already be connected. Without it the connect calls answer 404 Jira is not connected.

Connect the Jira writer

POST/v1/integrations/jira/writer

scopeintegrations:write

Connects or updates the Jira writer. This is the only route that accepts a service-account token, so a token is sent over HTTPS by an admin and never through a chat with an agent.

modeenumrequired

service_account or connector_fallback.

emailstring

service_account only. The service account's Atlassian email, up to 320 characters. Send it together with apiToken.

apiTokenstring

service_account only. A scoped Atlassian API token, 8 to 500 characters. It needs write:comment:jira, write:comment.property:jira and read:comment.property:jira, plus read:comment:jira to read comments back. nima checks the credentials against Jira when you send them, and a bad pair is rejected. It is stored encrypted and never returned.

acknowledgedboolean

connector_fallback only. true confirms that comments appear as the person who connected Jira. Without it the writer stays disabled.

enabledboolean

Turn the writer on or off. Defaults to on for service_account and to the value of acknowledged for connector_fallback.

Send email and apiToken together or not at all: sending only one answers 400. With mode: "service_account" and neither, the call only switches an already-connected service account on or off, and answers 400 when none is connected.

The call is audited. It answers 200 with the status object, which never contains a credential.

modestring

The mode in force.

enabledboolean

Whether nima may post as this writer.

writerAccountIdstring | null

The Atlassian account id comments appear as.

writerDisplayNamestring | null

That account's display name.

scopesstring[]

The scopes recorded for the writer. For a service account these are the four you were told to grant, because Atlassian API tokens cannot be inspected.

missingScopesstring[]

Required scopes the writer lacks. Non-empty means replies are refused until it is fixed.

needsAcknowledgementboolean

connector_fallback was chosen but not acknowledged.

acknowledgedAtstring | null

ISO 8601 UTC time of the acknowledgement.

revisioninteger

Increments on every change.

connectionInvalidboolean

The credential stopped working. Send a new token, or reconnect Jira.

Connect a service account

curl -X POST https://api.getnima.io/v1/integrations/jira/writer \
  -H "Authorization: Bearer $NIMA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "service_account",
    "email": "nima@acme.example",
    "apiToken": "ATATT3x..."
  }'

{
  "mode": "service_account",
  "enabled": true,
  "writerAccountId": "5b10a2844c20165700ede21g",
  "writerDisplayName": "nima",
  "scopes": [
    "read:comment:jira",
    "write:comment:jira",
    "read:comment.property:jira",
    "write:comment.property:jira"
  ],
  "missingScopes": [],
  "needsAcknowledgement": false,
  "acknowledgedAt": null,
  "revision": 1,
  "connectionInvalid": false
}

Get Jira writer status

GET/v1/integrations/jira/writer

scopeintegrations:write

Returns the same status object as the connect call. It answers 404 No Jira writer is connected when the workspace has none, and never returns a credential.

Connect the Jira writer without a token

POST/v1/integrations/jira/writer/mcp

scopeintegrations:writeMCP toolconnect_jira_writer

The agent-facing form of the Jira connect call. Its input has no email and no apiToken by design: a credential never travels through a chat.

modeenumrequired

service_account or connector_fallback.

acknowledgedboolean

connector_fallback only. Same meaning as above.

enabledboolean

Turn the writer on or off.

The response is { status, instructions }. status is the status object above, or null when nothing is connected. For service_account when no service account is connected yet, the call changes nothing and returns instructions that tell an admin to send the token to POST /v1/integrations/jira/writer. Once a service account is connected, this route can switch it on or off. With connector_fallback and acknowledged: true it connects the writer directly.

Response before a token exists

{
  "status": null,
  "instructions": "To connect a dedicated service account, an admin sends its Atlassian email and a scoped API token ... to POST /v1/integrations/jira/writer ..."
}

The comment scopes are deliberately not part of the normal Jira connect consent. A connector_fallback writer therefore reports write:comment:jira, write:comment.property:jira and read:comment.property:jira in missingScopes, and nima refuses to reply through it. Use service_account for Jira replies today. The connector's own scope table is on the Jira integration page.

Linear writer

The Linear writer lets nima reply on Linear issues as the person who connected Linear. That is the only mode: an app identity of its own is not available yet. Every reply waits for approval and cannot be made automatic.

Enabling the Linear writer does not yet make nima comment on Linear. No watch, rule or conversation proposes a Linear reply today, and Linear does not emit ticket events into outbound actions. The connection is ready for when it does.

Enable the Linear writer

POST/v1/integrations/linear/writer

scopeintegrations:writeMCP toolconnect_linear_writer

Enables the Linear writer after an admin acknowledges that replies will appear as the person who connected Linear. Linear must already be connected, or the call answers 404 Linear is not connected.

acknowledgedbooleanrequired

true confirms that replies appear as the connecting person and that each one waits for approval. Without it the writer stays disabled.

enabledboolean

Turn the writer on or off. Defaults to on when acknowledged is true.

Answers 200 with the status object. The call is audited, and no credential is ever returned.

modestring

Always connector_fallback.

enabledboolean

Whether nima may reply as the connecting person.

needsAcknowledgementboolean

The admin has not acknowledged yet.

acknowledgedAtstring | null

ISO 8601 UTC time of the acknowledgement.

revisioninteger

Increments on every change.

connectionInvalidboolean

The Linear connection stopped working. Reconnect Linear.

Get Linear writer status

GET/v1/integrations/linear/writer

scopeintegrations:write

Returns the same status object as the enable call. It answers 404 No Linear writer is enabled when the workspace has none.

Writer connection errors

Writer routes answer with the shared error shape from Errors.

Status	When
`400`	The body fails validation (the `details.issues` list names each field), or a Jira `email` arrives without `apiToken`, or a `service_account` toggle has no service account to toggle.
`403` `INSUFFICIENT_PERMISSIONS`	The caller is not a current owner or admin, the key lacks `integrations:write`, or a GitHub check fails (no active read-only integration, writer on a different account, `pull_requests: write` missing).
`404`	Jira or Linear is not connected, or no Jira or Linear writer exists yet for the status route.
`409`	The GitHub writer binding changed while you were changing it. Re-read and retry.
`503`	The GitHub writer App is not configured on this deployment.

Where writer connections lead

A connected Jira or Linear writer is one of the checks in front of every outbound reply. Read the outbound actions concept for the whole path, Actions to approve or discard what is waiting, and Action policies to decide which replies need approval. The tool-by-tool reference is on operation tools for GitHub and outbound tools for Jira and Linear.