AI visibility settings
`/geo-settings`
One page of records, newest first unless you say otherwise, with the total count in meta so you know how far to paginate.
Required scope: geo-settings:read.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
page?integer1-based. meta.totalPages says how many there are.
1 <= value1per_page?integerRows per page. A value above 200 returns 400 - never a silent clamp.
1 <= value <= 20050sort?stringPrefix with - for descending. An undeclared sort returns 400.
"-createdAt""createdAt""-createdAt""updatedAt""-updatedAt""brand""-brand"q?stringCase-insensitive "contains", across: brand, domain.
filter[clientId]?stringExact match on clientId.
filter[enabled]?stringExact match on enabled.
"true""false"filter[frequency]?stringExact match on frequency.
filter[country]?stringExact match on country.
filter[locale]?stringExact match on locale.
filter[portalVisible]?stringExact match on portalVisible.
"true""false"The requested page.
application/json- response
data*array<>meta*curl -X GET 'https://api.usedashly.com/v1/geo-settings'{ "data": [ { "id": "string", "clientId": "string", "brand": "string", "domain": "string", "aliases": null, "competitors": null, "country": "string", "locale": "string", "engines": null, "models": null, "frequency": "string", "portalVisible": true, "enabled": true, "activatedAt": "2019-08-24T14:15:22Z", "lastRunAt": "2019-08-24T14:15:22Z", "lastError": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" } ], "meta": { "page": 0, "perPage": 0, "total": 0, "totalPages": 0 }}Links are given as the target's public id (clientId: "hsbftmp3f5"); the API resolves them server-side. Fields the database requires but the interface decides for you are filled in the same way here.
Required scope: geo-settings:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
brand*string1 <= length <= 120domain?|nullaliases?array<>items <= 25competitors?array<>items <= 25country?string2 <= length <= 2locale?string"fr""en"engines*array<>1 <= itemsmodels?array<>frequency?string"daily""weekly""monthly"portalVisible?booleanclientId*stringcreatedAt?stringWhen this actually happened, for an import. Past dates only; defaults to now. updatedAt follows it unless the body sets one.
date-timeCreated. The body is the new record, as a read would return it.
application/json- response
data*curl -X POST 'https://api.usedashly.com/v1/geo-settings' \ -H 'Content-Type: application/json' \ -d '{ "brand": "string", "engines": [ "chatgpt" ], "clientId": "string"}'{ "data": { "id": "string", "clientId": "string", "brand": "string", "domain": "string", "aliases": null, "competitors": null, "country": "string", "locale": "string", "engines": null, "models": null, "frequency": "string", "portalVisible": true, "enabled": true, "activatedAt": "2019-08-24T14:15:22Z", "lastRunAt": "2019-08-24T14:15:22Z", "lastError": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }}The full record, custom fields included when the resource carries them. A record from another agency is a 404, not a 403 - its existence is not ours to confirm.
Required scope: geo-settings:read.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe record's public id (hsbftmp3f5), as returned in the id field. An internal UUID returns 404.
Found.
application/json- response
data*curl -X GET 'https://api.usedashly.com/v1/geo-settings/string'{ "data": { "id": "string", "clientId": "string", "brand": "string", "domain": "string", "aliases": null, "competitors": null, "country": "string", "locale": "string", "engines": null, "models": null, "frequency": "string", "portalVisible": true, "enabled": true, "activatedAt": "2019-08-24T14:15:22Z", "lastRunAt": "2019-08-24T14:15:22Z", "lastError": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }}A partial update: only the fields you send change. One exception - customFields is replaced wholesale, not merged, so sending it with a single key clears the others. Read the record, merge, then write.
Required scope: geo-settings:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe record's public id (hsbftmp3f5), as returned in the id field. An internal UUID returns 404.
application/json- body
brand?string1 <= length <= 120domain?|nullaliases?array<>items <= 25competitors?array<>items <= 25country?string2 <= length <= 2locale?string"fr""en"engines?array<>1 <= itemsmodels?array<>frequency?string"daily""weekly""monthly"portalVisible?booleanUpdated. The body is the record as it now stands.
application/json- response
data*curl -X PATCH 'https://api.usedashly.com/v1/geo-settings/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": { "id": "string", "clientId": "string", "brand": "string", "domain": "string", "aliases": null, "competitors": null, "country": "string", "locale": "string", "engines": null, "models": null, "frequency": "string", "portalVisible": true, "enabled": true, "activatedAt": "2019-08-24T14:15:22Z", "lastRunAt": "2019-08-24T14:15:22Z", "lastError": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }}Every verb this resource answers to, with its target and the JSON Schema of its body - the same contracts this document describes, readable at runtime.
Required scope: geo-settings:read.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
The available verbs.
application/json- response
data*array<>curl -X GET 'https://api.usedashly.com/v1/geo-settings/actions'{ "data": [ { "name": "string", "label": "string", "description": "string", "target": "item", "readOnly": true, "path": "string", "input": {} } ]}Starts a capture of the client's AI visibility now, in the background, exactly like the dashboard's capture button: every active question is asked on every configured engine and model, which SPENDS the agency's AI-visibility allowance. Requires the module to be switched on for the client (never possible through a key), the AI-visibility add-on, at least one active question, and a key whose owner holds reports.manage. Answers at once with status: started; the capture takes a few minutes. Read the result with GET /v1/clients/{id}/actions/ai-visibility, and a later refusal (credits exhausted) in lastError of this configuration.
Does what the dashboard's runGeoCaptureAction does - same implementation, so the two cannot diverge. Takes no body.
Required scope: geo-settings:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255Done.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X POST 'https://api.usedashly.com/v1/geo-settings/string/actions/capture'{ "data": null}Adds and/or removes competitor brand names on this AI visibility configuration without resending the list (add, remove; case is ignored, a name already present keeps its spelling). At most 25 competitors. Returns the resulting competitors. Changes nothing on any invoice; the next capture measures share of voice against the new list.
Does what the dashboard's saveGeoSettingsAction does - same implementation, so the two cannot diverge.
Required scope: geo-settings:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
add?array<>items <= 25remove?array<>items <= 25Done.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X POST 'https://api.usedashly.com/v1/geo-settings/string/actions/edit-competitors' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": null}Adds and/or removes other spellings that count as the client's brand (add, remove; case is ignored). At most 25 aliases. Returns the resulting aliases.
Does what the dashboard's saveGeoSettingsAction does - same implementation, so the two cannot diverge.
Required scope: geo-settings:write.
bearerAuthAuthorizationBearer <token>Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.
id*stringThe public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.
Idempotency-Key?stringA value you choose (a UUID is the usual one), 8 to 255 characters of A-Z a-z 0-9 _ . : -. Retrying with the same key returns the first call's answer instead of creating a second record, for seven days. The same key with a different body returns 409.
8 <= length <= 255application/json- body
add?array<>items <= 25remove?array<>items <= 25Done.
application/json- response
data*unknownThe action's result; its shape depends on the verb.
curl -X POST 'https://api.usedashly.com/v1/geo-settings/string/actions/edit-aliases' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": null}