> ## Documentation Index > Fetch the complete documentation index at: https://docs-stg.outerlayer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Replace a custom automation > Replaces the whole automation, so a field left out takes its default. To turn the automation on or off, send the whole body with a new `status`. The trigger type and, for a webhook automation, its sender cannot change. Send `signingSecret` to replace the secret of a Sentry or PagerDuty automation. A body with none keeps the stored secret. The change takes effect for the next event the automation answers. A save by a member sets the count of failed runs in a row to zero and clears the switch-off, so turning an automation back on, and the Keep it off action, both save. An automation with no creator takes the saving member as its creator. A creator that is set never changes. ## OpenAPI ````yaml /openapi.yaml put /v1/apps/{appId}/custom-automations/{automationId} openapi: 3.0.3 info: contact: email: hello@outerlayer.ai url: https://www.outerlayer.ai description: >- The OuterLayer Gateway API lets you ingest coding-agent sessions and record evidence of work programmatically. Most teams reach it through the `outerlayer` CLI, which calls it for them. Call it directly to build your own integration or to automate what the dashboard does. Versioning: every endpoint is prefixed with `/v1/`. Breaking changes ship under a new version prefix (`/v2/`, etc.) with a 90-day-minimum deprecation window; anything additive lands on the current prefix. Vocabulary: the dashboard calls this API's `app` a **factory** — the unit that owns a set of repositories, the agent sessions worked on them, and the evidence they produce. They are the same entity. The API keeps `app` in its paths, headers, and field names because those are a published contract; only the product surface was renamed. title: OuterLayer Gateway API version: '1.0' servers: - description: Production (OuterLayer Cloud) url: https://api.outerlayer.ai - description: Local dev server (self-hosted gateway) url: http://localhost:9418 security: - AppId: [] BearerAuth: [] tags: - description: >- What a CLI login token can read about its owner without naming a factory, such as the factories they can use. name: Account - description: >- The route a fleet machine asks for its next managed build on. A fleet machine is a machine OuterLayer operates. name: Fleet - description: >- The CLI version a gateway names to its runners, set with the gateway's runner version key. name: Runner version - description: >- Coding-agent session ingest (outerlayer sync) and content-addressed session images. name: Agents - description: >- Evidence artifacts (screenshots, recordings, reports, logs) emitted as proof of a change and anchored to pull requests. name: Artifacts - description: >- Pass/fail outcomes of checks run in your own CI or compute, anchored to pull requests with the run URL as proof. name: Emitted Results - description: >- The acceptance criteria of a work item, recorded as one list. The Criteria tab, its count and the item status read that list. name: Criteria - description: >- What any agent found wrong about a change under review or about a rule it ran on, recorded on a work item. name: Findings - description: >- Find, file and edit the issue a spec lives in, through OuterLayer, with no tracker credential on the caller's side. name: Specs - description: >- Add or remove a source's statement that it is working on an issue or pull request, and read what is currently live. name: Work Items - description: >- What the factory's GitHub App installation lets builds do on each connected repository, and whether each default branch requires a pull request. name: Repositories - description: >- The runs of a schedule automation: a runner claims a run, asks for its read token and ends it, and the run's agent reports each issue it found or that it found nothing. name: Schedule runs - description: >- A runner host's heartbeat — its CLI version, slots and last request for work — and the factory's list of hosts with a derived status. name: Hosts - description: Query server feature availability. name: Capabilities - description: Per-model LLM pricing data. Public, unauthenticated. name: Pricing - description: >- Create, list, and revoke factory API keys. Plaintext returned exactly once at creation. name: API Keys - description: >- Factory CRUD — a factory is owned by an organization and is the unit every other resource hangs off. Lets a headless agent provision one without the dashboard. name: Apps - description: >- Agent-coding session list and full transcript reads, with actor-privacy controls for machine keys. name: Sessions - description: >- Per-model token spend and fleet-wide agent behavior tiles, including two-window comparisons. name: Metrics - description: Synced-commit history of the app's `.outerlayer/` context tree. name: Context - description: >- Session→PR attribution: which agent sessions produced which pull requests, and what each attributed PR cost. name: PRs - description: Service health checks. name: Health - description: >- Org member and role administration, authenticated with an org-scoped management API key (`olk_…`) minted in the dashboard's settings. name: Org Management - description: OAuth 2.1 discovery metadata for MCP connector clients. name: OAuth paths: /v1/apps/{appId}/custom-automations/{automationId}: put: tags: - Apps summary: Replace a custom automation description: >- Replaces the whole automation, so a field left out takes its default. To turn the automation on or off, send the whole body with a new `status`. The trigger type and, for a webhook automation, its sender cannot change. Send `signingSecret` to replace the secret of a Sentry or PagerDuty automation. A body with none keeps the stored secret. The change takes effect for the next event the automation answers. A save by a member sets the count of failed runs in a row to zero and clears the switch-off, so turning an automation back on, and the Keep it off action, both save. An automation with no creator takes the saving member as its creator. A creator that is set never changes. operationId: replace-custom-automation parameters: - in: path name: appId required: true schema: format: uuid type: string - in: path name: automationId required: true schema: format: uuid type: string requestBody: content: application/json: schema: additionalProperties: false properties: dailyLimit: default: 5 description: >- For an issue automation, the most builds it can request in the last 24 hours. For a webhook automation, the most issues it files in the last 24 hours. maximum: 100 minimum: 1 type: integer instructions: default: null description: >- Standing instructions for each build the automation requests. The build treats them as instructions and treats the issue's text as data. A webhook automation has none. maxLength: 2000 nullable: true type: string name: description: The name the member gave the automation. maxLength: 100 minLength: 1 type: string signingSecret: description: >- The secret that Sentry or PagerDuty signs its requests with. Required to add a Sentry or PagerDuty automation. Send it again to replace the stored secret. OuterLayer never returns it. An Any JSON automation takes none, because OuterLayer makes its secret. maxLength: 500 minLength: 1 type: string status: default: 'on' description: The automation's switch. enum: - 'on' - 'off' type: string trigger: oneOf: - description: An issue is opened. properties: labels: description: >- The labels the new issue must have, all of them. An empty list matches every new issue. items: pattern: ^\S(?:[ \S]{0,48}\S)?$ type: string maxItems: 10 type: array scope: description: >- The source inside the tracker: a repository (`owner/repo`) for GitHub, a team key for Linear or a project key for Jira. It must be one of the factory's sources. maxLength: 200 minLength: 1 type: string tracker: description: The tracker the issue lives in. enum: - github - linear - jira type: string type: enum: - issue_opened type: string required: - type - tracker - scope - labels type: object - description: A label is added to an issue. properties: label: description: The label whose addition starts the automation. pattern: ^\S(?:[ \S]{0,48}\S)?$ type: string scope: description: >- The source inside the tracker: a repository (`owner/repo`) for GitHub, a team key for Linear or a project key for Jira. It must be one of the factory's sources. maxLength: 200 minLength: 1 type: string tracker: description: The tracker the issue lives in. enum: - github - linear - jira type: string type: enum: - issue_labeled type: string required: - type - tracker - scope - label type: object - description: A signed request arrives at the automation's URL. properties: alertKey: default: '' description: >- The alert field that names one alert, such as `{{ data.event.issue_id }}`. While an issue that the automation filed for a key is open, a new alert with the same key files nothing. Required for Sentry and PagerDuty. Empty is allowed for Any JSON, where each alert then files its own issue. maxLength: 200 type: string body: default: '' description: >- The issue's body, with the same fields. OuterLayer adds a last line that names the automation and the alert key. maxLength: 5000 type: string scope: description: >- The source inside the tracker: a repository (`owner/repo`) for GitHub, a team key for Linear or a project key for Jira. It must be one of the factory's sources. maxLength: 200 minLength: 1 type: string sender: description: >- `sentry` and `pagerduty` check the sender's own signature with the secret the member pastes. `any_json` checks the Standard Webhooks signature with a secret that OuterLayer makes. enum: - sentry - pagerduty - any_json type: string title: description: >- The issue's title. A field of the alert goes in double braces, such as `{{ data.event.title }}`. maxLength: 300 minLength: 1 type: string tracker: description: The tracker the issue lives in. enum: - github - linear - jira type: string type: enum: - webhook type: string required: - type - sender - tracker - scope - title type: object - description: >- A set time arrives. A run reads the repository with the automation's instructions and reports the issues it finds. properties: repository: description: >- The repository the run reads, as `owner/repo`. It must be a GitHub repository of the factory. The run cannot change it. maxLength: 200 minLength: 1 type: string schedule: description: How often the automation runs. oneOf: - description: At the start of each hour. properties: kind: enum: - hourly type: string required: - kind type: object - description: Every day at a time. properties: kind: enum: - daily type: string time: description: >- The time of day, `HH:MM` in 24 hours, in the automation's time zone. pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ type: string required: - kind - time type: object - description: Monday to Friday at a time. properties: kind: enum: - weekdays type: string time: description: >- The time of day, `HH:MM` in 24 hours, in the automation's time zone. pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ type: string required: - kind - time type: object - description: Once a week, on a day at a time. properties: day: description: The day of the week. enum: - monday - tuesday - wednesday - thursday - friday - saturday - sunday type: string kind: enum: - weekly type: string time: description: >- The time of day, `HH:MM` in 24 hours, in the automation's time zone. pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ type: string required: - kind - time - day type: object scope: description: >- Where the issues of a run are filed: the same repository, or a Linear team or Jira project of the factory. maxLength: 200 minLength: 1 type: string timeZone: description: >- The IANA time zone the schedule is read in, such as `Europe/London`. maxLength: 64 minLength: 1 type: string tracker: description: The tracker where the issues of a run are filed. enum: - github - linear - jira type: string type: enum: - schedule type: string required: - type - schedule - timeZone - repository - tracker - scope type: object whose: description: >- Required for an issue trigger. A webhook automation has none. enum: - members - anyone type: string required: - name - trigger type: object responses: '200': content: application/json: schema: properties: data: properties: createdAt: type: string creator: description: >- The member who added the automation, or the first member who saved it when it had none. `null` when it has none, or when the member left. nullable: true properties: membershipId: format: uuid type: string name: description: >- The creator's name as recorded when the automation recorded the creator. Empty when the member had no name. type: string required: - membershipId - name type: object dailyLimit: type: integer failureStreak: description: >- The failed runs in a row. A run with the result `found`, `nothing`, `filed` or `built` sets it to zero, and so does a save by a member. minimum: 0 type: integer hookId: description: >- The random id in a webhook automation's URL, `/api/webhooks/automations/{hookId}` on the dashboard. Not set for an issue automation. type: string id: format: uuid type: string instructions: nullable: true type: string name: description: The name the member gave the automation. maxLength: 100 minLength: 1 type: string nextDueAt: description: >- The next due time of a schedule automation that is on, in UTC. `null` when the automation is off. Not set for any other automation. nullable: true type: string noticesTo: description: >- Who gets the automation's notices now. `creator`: the creator is an active member who holds `factory.update` for the factory. `admins`: the factory's owners and admins, because the automation has no creator or its creator cannot edit the factory. enum: - creator - admins type: string 'off': description: >- Set while OuterLayer's switch-off stands: `failed_runs` (five runs in a row failed) or `no_runner` (no runner took a run in 7 days), and when. `null` otherwise. A save by a member clears it. nullable: true properties: at: type: string reason: enum: - failed_runs - no_runner type: string required: - reason - at type: object signingSecret: description: >- Whether a webhook automation has a signing secret. Never the secret of a Sentry or PagerDuty automation. properties: setAt: description: >- When the secret was set, or `null` when none is set. nullable: true type: string value: description: >- The secret OuterLayer made for an Any JSON automation. Only the answer that adds the automation holds it, and no later answer does. type: string required: - setAt type: object status: enum: - 'on' - 'off' type: string trigger: oneOf: - description: An issue is opened. properties: labels: description: >- The labels the new issue must have, all of them. An empty list matches every new issue. items: pattern: ^\S(?:[ \S]{0,48}\S)?$ type: string maxItems: 10 type: array scope: description: >- The source inside the tracker: a repository (`owner/repo`) for GitHub, a team key for Linear or a project key for Jira. It must be one of the factory's sources. maxLength: 200 minLength: 1 type: string tracker: description: The tracker the issue lives in. enum: - github - linear - jira type: string type: enum: - issue_opened type: string required: - type - tracker - scope - labels type: object - description: A label is added to an issue. properties: label: description: >- The label whose addition starts the automation. pattern: ^\S(?:[ \S]{0,48}\S)?$ type: string scope: description: >- The source inside the tracker: a repository (`owner/repo`) for GitHub, a team key for Linear or a project key for Jira. It must be one of the factory's sources. maxLength: 200 minLength: 1 type: string tracker: description: The tracker the issue lives in. enum: - github - linear - jira type: string type: enum: - issue_labeled type: string required: - type - tracker - scope - label type: object - description: A signed request arrives at the automation's URL. properties: alertKey: default: '' description: >- The alert field that names one alert, such as `{{ data.event.issue_id }}`. While an issue that the automation filed for a key is open, a new alert with the same key files nothing. Required for Sentry and PagerDuty. Empty is allowed for Any JSON, where each alert then files its own issue. maxLength: 200 type: string body: default: '' description: >- The issue's body, with the same fields. OuterLayer adds a last line that names the automation and the alert key. maxLength: 5000 type: string scope: description: >- The source inside the tracker: a repository (`owner/repo`) for GitHub, a team key for Linear or a project key for Jira. It must be one of the factory's sources. maxLength: 200 minLength: 1 type: string sender: description: >- `sentry` and `pagerduty` check the sender's own signature with the secret the member pastes. `any_json` checks the Standard Webhooks signature with a secret that OuterLayer makes. enum: - sentry - pagerduty - any_json type: string title: description: >- The issue's title. A field of the alert goes in double braces, such as `{{ data.event.title }}`. maxLength: 300 minLength: 1 type: string tracker: description: The tracker the issue lives in. enum: - github - linear - jira type: string type: enum: - webhook type: string required: - type - sender - tracker - scope - title type: object - description: >- A set time arrives. A run reads the repository with the automation's instructions and reports the issues it finds. properties: repository: description: >- The repository the run reads, as `owner/repo`. It must be a GitHub repository of the factory. The run cannot change it. maxLength: 200 minLength: 1 type: string schedule: description: How often the automation runs. oneOf: - description: At the start of each hour. properties: kind: enum: - hourly type: string required: - kind type: object - description: Every day at a time. properties: kind: enum: - daily type: string time: description: >- The time of day, `HH:MM` in 24 hours, in the automation's time zone. pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ type: string required: - kind - time type: object - description: Monday to Friday at a time. properties: kind: enum: - weekdays type: string time: description: >- The time of day, `HH:MM` in 24 hours, in the automation's time zone. pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ type: string required: - kind - time type: object - description: Once a week, on a day at a time. properties: day: description: The day of the week. enum: - monday - tuesday - wednesday - thursday - friday - saturday - sunday type: string kind: enum: - weekly type: string time: description: >- The time of day, `HH:MM` in 24 hours, in the automation's time zone. pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ type: string required: - kind - time - day type: object scope: description: >- Where the issues of a run are filed: the same repository, or a Linear team or Jira project of the factory. maxLength: 200 minLength: 1 type: string timeZone: description: >- The IANA time zone the schedule is read in, such as `Europe/London`. maxLength: 64 minLength: 1 type: string tracker: description: >- The tracker where the issues of a run are filed. enum: - github - linear - jira type: string type: enum: - schedule type: string required: - type - schedule - timeZone - repository - tracker - scope type: object updatedAt: type: string whose: description: Not set for a webhook automation. enum: - members - anyone type: string required: - id - name - trigger - instructions - dailyLimit - status - creator - noticesTo - failureStreak - 'off' - createdAt - updatedAt type: object required: - data type: object description: The stored automation. '400': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: >- The body fails the schema, or names a source the factory does not read (`unknown_source`). '401': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Missing or invalid API key. '403': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Caller lacks 'factory.update' permission. '404': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: The factory holds no automation with this id (`not_found`). components: securitySchemes: AppId: description: Factory id the request is scoped to. in: header name: X-Outerlayer-App-Id type: apiKey BearerAuth: description: API key (sk_outerlayer_*) scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.