> ## Documentation Index > Fetch the complete documentation index at: https://docs.appgoat.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create action > Computes the before → after `diff` from the live account and runs guardrails (policy / tone / claims probabilities for text, plus deterministic checks like character limits and bid jumps). Free. - `dry_run: true` → a `draft` (24 h) with the diff: show it to the user. To go ahead, call `POST /v1/actions/{id}/approve`. - otherwise → `pending_approval` (a person approves it in the dashboard, link in `approve_url`), or `applied` immediately when the org has an auto-apply rule for this type that the guardrail score clears (Studio, 1 credit). Blocking check failures (over a character limit, nothing to change, not editable) return 400 with `checks` (a dry run returns them in `guardrail.checks_failed` instead). Params per type (`app` = a linked App Store id or package name, `locale` like en-US): - `review.reply` (asc, play_console): `{ app, review_id, text }` — review ids from GET /v1/connections/{id}/reviews. Play replies ≤ 350 chars. - `listing.update` (asc, play_console): `{ app, locale, fields: { name|title, subtitle, description, promotional_text, whats_new, marketing_url, support_url, privacy_policy_url } }` (Play: title, short_description, full_description, video). - `keywords.set` (asc): `{ app, locale, keywords: [..] | "a,b,c", mode?: replace|add|remove }` — 100 bytes comma-joined. - `screenshots.upload` (asc, play_console): `{ app, locale, display_type: APP_IPHONE_67 … (asc) | image_type: phoneScreenshots … (play), images: [{ url }], replace?: true }`. - `ads.keyword.bid` (apple_ads): `{ campaign_id, ad_group_id, keywords: [{ id, bid?, status?: ENABLED|PAUSED }], max_increase?: 1 }`. - `ads.keyword.add` (apple_ads): `{ campaign_id, ad_group_id, keywords: [{ text, match_type?: EXACT|BROAD, bid? }] }`. - `ads.negative.add` (apple_ads): `{ campaign_id, ad_group_id?, keywords: [{ text, match_type? }] }`. ## OpenAPI ````yaml openapi.json POST /actions openapi: 3.1.0 info: title: AppGoat API version: 1.0.0 summary: App Store + Google Play data for agents and apps. description: > Every app and developer in both stores, daily top charts, reviews, change feeds, metric history and keyword (search-rank) intelligence. **Conventions** - `{app}` accepts anything that identifies an app: an App Store id (`284882215`, `id284882215`), a Play package (`com.spotify.music`), an Apple bundle id (`com.spotify.client`), a store URL, `apple:` / `play:`, or a name (`spotify` → best match, with a warning in `meta.warnings`). Add `store=apple|play` to disambiguate. `data.linked` is the same app in the other store when we know it. - Freshness is automatic: app-scoped reads refresh data older than `max_age` seconds from the store first (1 credit per country fetched, capped at 10). `wait=true` (default) blocks up to ~25 s; on timeout, or with `wait=false`, you get the cached data with `meta.freshness.refreshing: true` and a `job_id` to poll at `GET /v1/jobs/{id}` (free). - `country` defaults to `us`; pass a comma list (paid plans) or `all` (Studio). - `include=` adds sections, `fields=` keeps only the listed top-level fields, lists page with `cursor` (pass `meta.next_cursor` back unchanged). - Every success is `{ data, meta }`; `meta.credits_used` is what the call cost and `meta.credits_remaining` what is left. Errors are `{ error: { code, message, hint, docs } }`: read `hint`, it says what to do next. - `x-credits` on each operation documents its price. - Watches turn store changes into events: `POST /v1/watches`, then poll `GET /v1/events` or add a webhook (`POST /v1/webhooks`). Watches, events and webhooks are free; only the plan's watched-app and keyword-slot limits apply. `/v1/tracked-keywords` is deprecated: use keyword watches. contact: email: support@appgoat.ai url: https://appgoat.ai servers: - url: https://api.appgoat.ai/v1 security: - apiKey: [] tags: - name: Apps - name: Search & charts - name: Keywords - name: Developers - name: Audits - name: Watches & events description: >- Watch apps, competitors and keywords; significant changes become events (feed, webhooks, Slack, GitHub, daily email digest). - name: Webhooks - name: Connections - name: Actions - name: Jobs - name: Account paths: /actions: post: tags: - Actions summary: >- Propose a write to a connected account (reply to a review, update a listing, set keywords, upload screenshots, change Apple Ads bids / keywords / negatives); always start with dry_run=true. description: > Computes the before → after `diff` from the live account and runs guardrails (policy / tone / claims probabilities for text, plus deterministic checks like character limits and bid jumps). Free. - `dry_run: true` → a `draft` (24 h) with the diff: show it to the user. To go ahead, call `POST /v1/actions/{id}/approve`. - otherwise → `pending_approval` (a person approves it in the dashboard, link in `approve_url`), or `applied` immediately when the org has an auto-apply rule for this type that the guardrail score clears (Studio, 1 credit). Blocking check failures (over a character limit, nothing to change, not editable) return 400 with `checks` (a dry run returns them in `guardrail.checks_failed` instead). Params per type (`app` = a linked App Store id or package name, `locale` like en-US): - `review.reply` (asc, play_console): `{ app, review_id, text }` — review ids from GET /v1/connections/{id}/reviews. Play replies ≤ 350 chars. - `listing.update` (asc, play_console): `{ app, locale, fields: { name|title, subtitle, description, promotional_text, whats_new, marketing_url, support_url, privacy_policy_url } }` (Play: title, short_description, full_description, video). - `keywords.set` (asc): `{ app, locale, keywords: [..] | "a,b,c", mode?: replace|add|remove }` — 100 bytes comma-joined. - `screenshots.upload` (asc, play_console): `{ app, locale, display_type: APP_IPHONE_67 … (asc) | image_type: phoneScreenshots … (play), images: [{ url }], replace?: true }`. - `ads.keyword.bid` (apple_ads): `{ campaign_id, ad_group_id, keywords: [{ id, bid?, status?: ENABLED|PAUSED }], max_increase?: 1 }`. - `ads.keyword.add` (apple_ads): `{ campaign_id, ad_group_id, keywords: [{ text, match_type?: EXACT|BROAD, bid? }] }`. - `ads.negative.add` (apple_ads): `{ campaign_id, ad_group_id?, keywords: [{ text, match_type? }] }`. operationId: createAction requestBody: required: true content: application/json: schema: type: object required: - type - params properties: type: $ref: '#/components/schemas/ActionType' connection: type: string description: >- Connection id; optional when exactly one active connection fits the type (and params.app). params: type: object additionalProperties: true dry_run: type: boolean default: false source: type: string description: >- Who proposes it: api, mcp or playbook: (shown in the approvals list). example: type: review.reply dry_run: true source: playbook:reply-to-every-review params: app: '1234567890' review_id: 00000043-a2fa-4f01-0000-000000000000 text: >- Thanks for the detailed report! Version 2.4.1 fixes the login loop. responses: '201': description: The action (draft, pending_approval or applied). content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: data: $ref: '#/components/schemas/Action' '400': $ref: '#/components/responses/InvalidParam' '402': $ref: '#/components/responses/PaymentRequired' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '502': $ref: '#/components/responses/ProviderError' components: schemas: ActionType: type: string enum: - review.reply - listing.update - keywords.set - screenshots.upload - ads.keyword.bid - ads.keyword.add - ads.negative.add Envelope: type: object required: - data - meta properties: data: {} meta: $ref: '#/components/schemas/Meta' Action: type: object properties: id: type: string example: act_Qm3xXk2Lw9PaZr0cVb type: $ref: '#/components/schemas/ActionType' connection_id: type: string status: type: string enum: - draft - pending_approval - approved - applied - failed - rejected params: type: object additionalProperties: true diff: $ref: '#/components/schemas/Diff' guardrail: $ref: '#/components/schemas/Guardrail' result: description: What the provider returned when applied. error: type: - string - 'null' created_by: type: string description: api, mcp, playbook: or dashboard. approved_by: type: - string - 'null' description: user:, auto (rule) or api. rejected_reason: type: - string - 'null' credits: type: integer created_at: type: string format: date-time applied_at: type: - string - 'null' format: date-time expires_at: type: - string - 'null' format: date-time approve_url: type: - string - 'null' description: Dashboard page where a person approves it. audit: type: array description: Only on GET /actions/{id}. items: type: object properties: event: type: string actor: type: string at: type: string format: date-time detail: type: - object - 'null' additionalProperties: true Meta: type: object properties: credits_used: type: integer credits_remaining: type: integer description: Added by the gateway. request_id: type: string description: Added by the gateway. freshness: $ref: '#/components/schemas/Freshness' next_cursor: type: - string - 'null' store: $ref: '#/components/schemas/Store' warnings: type: array items: type: string description: Things to know (e.g. "resolved by name"); safe to show to the user. Diff: type: object properties: target: type: object additionalProperties: true description: >- What changes: app, locale, review (rating, text), campaign / ad group … changes: type: array items: type: object properties: field: type: string before: {} after: {} summary: type: string notes: type: array items: type: string Guardrail: type: object properties: status: type: string enum: - passed - flagged - unavailable - not_applicable score: type: number description: >- Lowest AI check probability (1 when none apply). Auto-apply rules compare this. checks: type: object additionalProperties: type: number description: >- Probability each holds: policy (store rules), tone (professional), claims (no risky promises), relevance (replies). warnings: type: array items: type: string checks_failed: type: array items: type: object properties: id: type: string severity: type: string enum: - block - warn message: type: string model: type: - string - 'null' Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - invalid_param - invalid_credentials - unauthorized - forbidden - insufficient_credits - plan_limit - free_audit_used - not_found - app_not_found - developer_not_found - job_not_found - conflict - not_ready - rate_limited - provider_error - internal_error - not_configured message: type: string hint: type: string description: What to do next. docs: type: string format: uri param: type: string Freshness: type: object properties: fetched_at: type: - string - 'null' format: date-time description: When the oldest requested country was last fetched from the store. age_seconds: type: - integer - 'null' stale: type: boolean description: Older than max_age (or missing). refreshing: type: boolean description: A store fetch is still running; poll job_id. job_id: type: - string - 'null' Store: type: string enum: - apple - play responses: InvalidParam: description: A parameter is missing or invalid (`error.param` names it). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_param message: limit must be ≤ 100 hint: Fix the parameter and retry. docs: https://appgoat.ai/docs/errors#invalid_param param: limit PaymentRequired: description: >- `insufficient_credits` (the call costs more than you have left; nothing was done) or `plan_limit` (a feature of a higher plan). content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- The state does not allow this (already applied, expired, connection read-only or invalid, account changed since the dry run). content: application/json: schema: $ref: '#/components/schemas/Error' ProviderError: description: >- App Store Connect / Google Play / Apple Ads answered with an error (message passed through). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Create a key at https://dash.appgoat.ai. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.