Introduction
The ads.txt Guru API allows you to control your account programmatically, this enables you to manage your domains, groups and ads.txt records using your own code, and most importantly enables you to streamline publisher aquisition by integrating the domain invite process into your publisher control panel.
HTTPS connections are used with either GET or POST parameters (HTTP connections are not permitted). These HTTPS connections are made to different URIs depending on the API function required, all of which must include the API protocol version. The API response is by default provided in JSON format, however the response can optionally be provided in PHP serialize() format, and optionally encoded using base64 encoding.
All API requests require your API key and secret which can be found under the Integrate section of your ads.txt Guru account.
Note, we will be providing language specific libraries to simplify integration, beginning with a PHP library in the near future. Please contact us for more information.
If you have any questions regarding API integration, please contact us.
# Example listing domains
curl https://adstxt.guru/api/1.0/domain/list/
-d key=KEY
-d secret=SECRET
# Example response
{
"success": true,
"domains": {
"1234": {
"id": "1234",
"tag": "abcdefgi01234567",
"name": "domain.com",
"protocol": "https",
"verify_key": "ABCDEFGU01234567",
"verified": "0",
"comment": "1",
"synchronize": "0",
"discovery": "1"
}
}
}
$api = atg_api('KEY', 'SECRET');
Authentication
API authentication is handled using the key and secret parameters, these are required for all API requests. Your API key and secret can be found under the Integrate section of your ads.txt Guru account.
API access must be enabled in the Integrate section of your ads.txt Guru account in order to access the API.
If your request has failed authentication then a 401 HTTP status code will be returned.
Parameters
| key: | string (required) Your 32 character API key. |
| secret: | string (required) Your 32 character API secret. |
| format: | string json, json64, serial or serial64. |
# Example request
curl https://adstxt.guru/api/1.0/
-d key=KEY
-d secret=SECRET
# Example authentication failed response
{
"success": false,
"reason": "authentication"
}
$api = atg_api('KEY', 'SECRET');
Responses & Errors
API responses are provided as arrays, either in JSON or PHP serialize() format.
The success value will always be included as true or false depending on the success of the request. The reason value will be returned when a request has not been successful, the core reasons are authentication, disabled and invalid, further reasons will be returned for specific functions.
API requests will typically be returned with a 200 HTTP status code, a 401 code will be returned when authentication has failed, a 400 code will be returned if the request was invalid, and a 429 code will be returned when the request has been rate limited (see Rate Limiting).
Unsuccessful reasons
| authentication: | Authentication has failed. |
| disabled: | API access is disabled in the Integrate section of your ads.txt Guru account. |
| invalid: | Request is invalid, either URI or parameters are incorrect. |
| rate-limit: | Too many requests for this API key within the rate limit window. See Rate Limiting. |
| maintenance: | API currently unavailable due to maintenance. |
| discontinued: | API protocol version no longer supported. |
# Example request
curl https://adstxt.guru/api/1.0/invalid/
-d key=KEY
-d secret=SECRET
# Example invalid request response
{
"success": false,
"reason": "invalid"
}
$api = atg_api('KEY', 'SECRET');
Rate Limiting
Heavyweight API endpoints are rate limited per API key to protect the service from accidental traffic bursts. Currently applies to validate/adstxt and compare/adstxt.
The current limit is 30 calls per 30 second rolling window per API key. When exceeded, the API returns a 429 HTTP status code with a rate-limit reason. If you have a legitimate use case that requires more, get in touch.
Every authenticated API response includes rate limit headers so well-behaved clients can self-throttle.
Response Headers
| X-RateLimit-Limit: | integer Maximum number of calls permitted per window. |
| X-RateLimit-Remaining: | integer Calls remaining in the current window after this request. |
| X-RateLimit-Window-Seconds: | integer Length of the rate limit window in seconds. |
| X-RateLimit-Reset: | integer Unix timestamp at which the oldest call in the current window will expire and free up capacity. |
| Retry-After: | integer (only on 429) Seconds to wait before retrying. |
429 Response Body
| success: | boolean Always false for a rate-limit response. |
| reason: | string Always rate-limit. |
| message: | string Human-readable explanation of the limit. |
| limit: | integer Maximum number of calls permitted per window. |
| remaining: | integer Always 0 in a rate-limit response. |
| window_seconds: | integer Length of the rate limit window in seconds. |
| reset_unix: | integer Unix timestamp at which the oldest call in the current window will expire. |
| retry_after_seconds: | integer Seconds to wait before retrying. |
# Example rate limited response headers
HTTP/2 429
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Window-Seconds: 30
X-RateLimit-Reset: 1715763600
Retry-After: 17
# Example rate limited response body
{
"success": false,
"reason": "rate-limit",
"message": "Too many requests for this API key. Limit is 30 calls per 30 seconds.",
"limit": 30,
"remaining": 0,
"window_seconds": 30,
"reset_unix": 1715763600,
"retry_after_seconds": 17
}
$api = atg_api('KEY', 'SECRET');
Domain
The domain functions allow you to manage the domains which would normally be managed under the Manage section of your ads.txt Guru account.
These functions give you complete control to add, edit and remove your domains.
Domain data is provided in what we refer to as the Domain Array which includes the domain values as outlined below.
Domain Array
| id: | integer Numeric domain ID. |
| tag: | string 16 character domain tag. |
| name: | string The domain name. |
| protocol: | string The domain protocol, either https or http. |
| verify_key: | string 16 character domain verification key. |
| verified: | integer 0 if domain has not been verified, 1 if domain has been verified. |
| verify_version: | string The # Version header observed in the domain's live ads.txt at the last verification check, or an empty string if our header was absent. Advisory only — it never affects verified. |
| comment: | integer 0 if comments will not be included in generated ads.txt file, 1 if comments will be included. |
| synchronize: | integer 1 if automatic synchronization is enabled (requires 'Connect FTP' or 'Connect WordPress' is configured), 0 if not enabled. |
| discover: | integer 1 if domain can be discovered using domain tag, 0 if discovery is disabled. |
# Example domain array
{
"id": "1234",
"tag": "abcdefgi01234567",
"name": "domain.com",
"protocol": "https",
"verify_key": "ABCDEFGU01234567",
"verified": "0",
"verify_version": "",
"comment": "1",
"synchronize": "0",
"discovery": "1"
}
$api = atg_api('KEY', 'SECRET');
domain/list
This function allows you to retrieve a list of all domains under your account.
Successful response values
| success: | boolean true |
| domains: |
array An array of Domain Arrays, each array record uses the domain ID as it's key. |
# Example request
curl https://adstxt.guru/api/1.0/domain/list/
-d key=KEY
-d secret=SECRET
# Example successful response
{
"success": true,
"domains": {
"1234" {
"id": "1234",
"tag": "abcdefgi01234567",
"name": "domain.com",
"protocol": "https",
"verify_key": "ABCDEFGU01234567",
"verified": "0",
"comment": "1",
"synchronize": "0",
"discovery": "1"
},
"1235" {
"id": "1235",
"tag": "abcdefgi01234568",
"name": "another.com",
"protocol": "http",
"verify_key": "ABCDEFGU01234568",
"verified": "1",
"comment": "1",
"synchronize": "1",
"discovery": "1"
}
}
}
$api = atg_api('KEY', 'SECRET');
domain/add
This function allows you to add a new domain to your account.
Parameters
| protocol: | string https or http. |
| name: | string (required) The domain name to be added, excluding the protocol. e.g. domain.com |
Unsuccessful reasons
| invalid: | Invalid name or protocol value. |
| duplicate: | Domain has already been added under this account. |
| conflict: | Domain has already been added under another account. |
| limit: | Maximum domains limit reached. |
Successful response values
| success: | boolean true |
| domain: |
array Domain Array. |
# Example request
curl https://adstxt.guru/api/1.0/domain/add/
-d key=KEY
-d secret=SECRET
-d protocol=https
-d name=domain.com
# Example duplicate domain response
{
"success": false,
"reason": "duplicate"
}
# Example successful response
{
"success": true,
"domain": {
"id": "1234",
"tag": "abcdefgi01234567",
"name": "domain.com",
"protocol": "https",
"verify_key": "ABCDEFGU01234567",
"verified": "0",
"comment": "1",
"synchronize": "0",
"discovery": "1"
}
}
$api = atg_api('KEY', 'SECRET');
domain/get
This function allows you to retrieve a specific domain under your account.
In addition to the standard Domain Array fields, this function returns the time of the last verification check (verify_time, a unix timestamp) and an advisory version-currency signal. version_current is the ads.txt version we currently publish for the domain; version_status compares it against the version observed in the live ads.txt at the last check (verify_version) and is one of current (the live file is up to date), behind (we re-checked after publishing and the live file is still serving an older version — a stale copy), or unknown (not verified, or not yet re-checked since your last change, so we make no claim — a freshly edited domain reads unknown until the next check rather than falsely reporting behind). version_match is a convenience boolean, true only when version_status is current. These values are advisory only and never affect verified.
Parameters
| domain: | integer (required) Numeric ID of domain you would like to retrieve. |
Successful response values
| success: | boolean true |
| domain: |
array Domain Array. |
# Example request
curl https://adstxt.guru/api/1.0/domain/get/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example successful response
{
"success": true,
"domain": {
"id": "1234",
"tag": "abcdefgi01234567",
"name": "domain.com",
"protocol": "https",
"verify_key": "ABCDEFGU01234567",
"verified": "1",
"verify_time": "1780516541",
"verify_version": "1.0.3",
"comment": "1",
"synchronize": "0",
"discovery": "1",
"version_current": "1.0.4",
"version_status": "behind",
"version_match": false
}
}
$api = atg_api('KEY', 'SECRET');
domain/edit
This function allows you to edit a domain under your account.
Parameters
| domain: | integer (required) Numeric ID of domain you would like to edit. |
| protocol: | string https or http. |
| name: | string The new domain name, excluding the protocol. e.g. domain.com |
| comment: | integer 0 if comments should not be included in generated ads.txt file, 1 if comments should be included. |
| synchronize: | integer 1 if automatic synchronization should be enabled (requires 'Connect FTP' or 'Connect WordPress' is configured), 0 if should not be enabled. |
| discover: | integer 1 if domain should be discoverable using domain tag, 0 if discovery should be disabled. |
Unsuccessful reasons
| invalid: | Invalid name or protocol value. |
| duplicate: | Domain has already been added under this account. |
| conflict: | Domain has already been added under another account. |
Successful response values
| success: | boolean true |
| domain: |
array Domain Array. |
# Example request
curl https://adstxt.guru/api/1.0/domain/edit/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d protocol=http
-d comment=0
# Example successful response
{
"success": true,
"domain": {
"id": "1234",
"tag": "abcdefgi01234567",
"name": "domain.com",
"protocol": "http",
"verify_key": "ABCDEFGU01234567",
"verified": "0",
"comment": "0",
"synchronize": "0",
"discovery": "1"
}
}
$api = atg_api('KEY', 'SECRET');
domain/remove
This function allows you to remove a specific domain under your account.
Parameters
| domain: | integer (required) Numeric ID of domain you would like to remove. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/domain/remove/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
domain/synchronize
This function allows you to provoke synchronization of a specific domain under your account.
This requires 'Connect FTP' or 'Connect WordPress' has been configured, although if neither are configured the API will retrieve the ads.txt file via HTTP to check it against the latest version, if matched then the synchronize is considered successful.
Parameters
| domain: | integer (required) Numeric ID of domain you would like to synchronize. |
Unsuccessful reasons
| error: | A system error has occurred. |
| noftp: | 'Connect FTP' and 'Connect WordPress' have not been configured. |
| connect: | FTP connection failed. |
| upload: | Connection was successful, but FTP upload failed. |
| wordpress: | WordPress connection failed. |
Successful response values
| success: | boolean true |
| method: | string ftp, wordpress, or http will be returned if 'Connect FTP' is not configured but the ads.txt file has already been manually uploaded. |
# Example request
curl https://adstxt.guru/api/1.0/domain/synchronize/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example 'Connect FTP' and 'Connect WordPress' not configured, and HTTP verification failed response
{
"success": false,
"reason": "noftp"
}
# Example FTP synchronize successful response
{
"success": true,
"method": "ftp"
}
# Example HTTP verification successful response
{
"success": true,
"method": "http"
}
$api = atg_api('KEY', 'SECRET');
domain/verify
This function allows you to provoke verification of a specific domain under your account.
Parameters
| domain: | integer (required) Numeric ID of domain you would like to verify. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/domain/verify/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
domain/hosting
This function enables Connect Hosting for a specific domain under your account, returning the hosted ads.txt URL. Direct your domain's /ads.txt path to this URL via 301 redirect and we will serve the latest version of your ads.txt automatically.
The endpoint is idempotent — calling it again for the same domain returns the same token and only updates the enabled flag if changed.
Parameters
| domain: | integer (required) Numeric ID of domain you would like to enable hosting for. |
| enabled: | integer (optional) 1 to enable hosting (default), 0 to disable. |
Unsuccessful reasons
| invalid: | Domain ID is missing, not numeric, or not owned by the authenticated user. |
Successful response values
| success: | boolean true |
| hosting: | array Contains domain, token, enabled, and url. |
# Example request
curl https://adstxt.guru/api/1.0/domain/hosting/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example successful response
{
"success": true,
"hosting": {
"domain": 1234,
"token": "AbCdEfGhIjKlMnOpQrStUvWxYz012345",
"enabled": "1",
"url": "https://adstxt.guru/hosting/AbCdEfGhIjKlMnOpQrStUvWxYz012345/ads.txt"
}
}
# Example disable request
curl https://adstxt.guru/api/1.0/domain/hosting/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d enabled=0
$api = atg_api('KEY', 'SECRET');
domain/wordpress
This function connects a WordPress installation to a specific domain under your account, using the Connect Data generated by the ads.txt Guru WordPress plugin. Once connected, ads.txt updates are pushed to the WordPress site automatically.
The WordPress plugin generates the Connect Data as a base64-encoded string and displays it within the plugin's settings page. Pass this string verbatim to this endpoint.
This endpoint runs the same live handshake against the WordPress URL as the web UI — if the plugin URL cannot be reached or rejects our credentials, the connection is not saved and the response includes a reason.
Parameters
| domain: | integer (required) Numeric ID of the domain to connect. |
| connect_data: | string (required, unless disconnect=1) Base64-encoded Connect Data string from the WordPress plugin. |
| disconnect: | integer (optional) 1 to remove the existing WordPress connection for this domain. |
Unsuccessful reasons
| invalid: | Domain ID is missing/not owned, or connect_data is missing/malformed/fails validation. |
| connect: | Live handshake with the WordPress URL failed (no response or rejected credentials). |
| code-{HTTP_CODE}: | The WordPress URL returned the given HTTP error code (e.g. code-403, code-404). Check the plugin URL is reachable and our IP is not blocked. |
Successful response values
| success: | boolean true |
| wordpress: | array Contains domain, url (when connecting), and connected (boolean). |
# Example connect request
curl https://adstxt.guru/api/1.0/domain/wordpress/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d connect_data=BASE64_BLOB_FROM_PLUGIN
# Example successful response
{
"success": true,
"wordpress": {
"domain": 1234,
"url": "https://example.com",
"connected": true
}
}
# Example disconnect request
curl https://adstxt.guru/api/1.0/domain/wordpress/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d disconnect=1
$api = atg_api('KEY', 'SECRET');
Domain Group
The domain group functions allow you to manage the groups which can collaborate with your domain, you can also request new groups collaborate with your domain using collaborator tags.
These functions do not allow you to manage invitations to collaborate with groups, these are managed with the Domain Invite functions. For clarification, a domain can request collaboration with a group, whereas a group can invite a domain to collaborate.
Group data is provided in what we refer to as the Domain Group Array which includes the group relationship values as outlined below, this should not be confused with the Domain Array or Group Array.
Domain Group Array
| id: | integer Numeric domain ID. |
| group: | string The group name. |
| trust: | boolean/array Returns false if group has not been certified, or an array containing organization and url values if the group is certified & trusted. |
| approved: | integer 1 if collaboration with this group has been approved, 0 if collaboration has not yet been approved. |
# Example domain group array
{
"id": "1234",
"group": "Example Group",
"trust": {
"organization": "Ad Network",
"url": "http://example.com/"
},
"approved": "1"
}
$api = atg_api('KEY', 'SECRET');
domain/group/list
This function allows you to list the groups which are collaborating with this domain.
Parameters
| domain: | integer (required) Numeric ID of domain. |
Successful response values
| success: | boolean true |
| groups: | array An array of Domain Group Arrays, each array record uses the request ID as it's key. |
# Example request
curl https://adstxt.guru/api/1.0/domain/group/list/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example successful response
{
"success": true,
"groups": {
"123": {
"id": "123",
"group": "Example Group",
"trust": {
"organization": "Ad Network",
"url": "http://example.com/"
},
"approved": "1"
},
"124": {
"id": "124",
"group": "Another Group",,
"trust": false,
"approved": "0"
},
}
}
$api = atg_api('KEY', 'SECRET');
domain/group/request
This function allows you to request collaboration with a group using their collaborator tag. Requests require approval by the group, except when they have enabled automatic approval.
Collaborator tags are only accessible to the group owner, they must in turn share their collaborator tag with you to enable you to submit a request.
Parameters
| domain: | integer (required) Numeric ID of domain. |
| tag: | string (required) 16 character collaborator tag. |
| message: | string A message to help the group determine your eligibility to collaborate, maximum length is 255 characters, usage of certain characters/symbols is restricted. |
Unsuccessful reasons
| invalid-tag: | Collaborator tag is invalid. |
| invalid-message: | Invalid message, either it exceeds 255 characters or contains restricted characters/symbols. |
| duplicate: | Duplicate request, collaboration with this group already exists or has already been requested. |
| limit: | Maximum publishers limit reached. |
Successful response values
| success: | boolean true |
| request: | array Domain Group Array. |
# Example request
curl https://adstxt.guru/api/1.0/domain/group/request/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d tag=abcdefgi01234567
-d message=My+publisher+account+username+is+ABC123.
# Example invalid tag response
{
"success": false,
"reason": "invalid-tag"
}
# Example successful response
{
"success": true,
"request": {
"id": "123",
"group": "Example Group",
"trust": false,
"approved": "0"
}
}
$api = atg_api('KEY', 'SECRET');
domain/group/remove
This function allows you to remove a group to discontinue collaboration.
Parameters
| domain: | integer (required) Numeric ID of domain. |
| group: | integer (required) Numeric ID of domain group request. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/domain/group/remove/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d group=123
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
Domain Invite
The domain invite functions allow you to view, approve and decline invitations you have received to collaborate with groups.
These functions do not allow you to manage existing group collaboration relationships, these are managed with the Domain Group functions. For clarification, a domain can request collaboration with a group, whereas a group can invite a domain to collaborate.
Invite data is provided in what we refer to as the Domain Invite Array which includes the invite relationship values as outlined below, this should not be confused with the Domain Array or Group Array. The Domain Invite Array follows the same format as the Domain Group Array with the addition of the message value.
Domain Invite Array
| id: | integer Numeric domain ID. |
| group: | string The group name. |
| trust: | boolean/array Returns false if group has not been certified, or an array containing organization and url values if the group is certified & trusted. |
| approved: | integer 1 if collaboration with this group has been approved, 0 if collaboration has not yet been approved. |
| message: | string A message from the group to help you determine the group's eligibility to collaborate. |
# Example domain invite array
{
"id": "1234",
"group": "Example Group",
"trust": {
"organization": "Ad Network",
"url": "http://example.com/"
},
"approved": "1",
"message": "Request from ABC Ad Network as discussed with, john@abcads.com."
}
$api = atg_api('KEY', 'SECRET');
domain/invite/list
This function allows you to list the invitations you have received to collaborate with groups.
Parameters
| domain: | integer (required) Numeric ID of domain. |
Successful response values
| success: | boolean true |
| invites: | array An array of Domain Invite Arrays, each array record uses the invite ID as it's key. |
# Example request
curl https://adstxt.guru/api/1.0/domain/invite/list/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example successful response
{
"success": true,
"invites": {
"123": {
"id": "123",
"group": "Example Group",
"trust": {
"organization": "Ad Network",
"url": "http://example.com/"
},
"approved": "0",
"message": "Request from ABC Ad Network as discussed with, john@abcads.com."
},
"124": {
"id": "124",
"group": "Another Group",
"trust": false,
"approved": "0",
"message": ""
},
}
}
$api = atg_api('KEY', 'SECRET');
domain/invite/approve
This function allows you to approve an invite. Once approved the invite becomes a domain group which can be managed with the Domain Group functions.
Parameters
| domain: | integer (required) Numeric ID of domain. |
| invite: | string (required) Numeric ID of invite. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/domain/invite/approve/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d invite=123
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
domain/invite/decline
This function allows you to decline an invite.
Parameters
| domain: | integer (required) Numeric ID of domain. |
| invite: | string (required) Numeric ID of invite. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/domain/invite/decline/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d invite=123
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
Domain Adstxt
The domain adstxt functions allow you to manage your ads.txt records, for example to add new ads.txt records or to download your ads.txt file.
Adstxt data is provided in what we refer to as the Domain Adstxt Array which includes all your ads.txt records in array format. The Domain Adstxt Array is fundamentally the same as the Group Adstxt array.
Domain Adstxt Array
| version: | version The numeric version number, e.g. 0.0.1. |
| records: | array An array of ads.txt records, as outlined below. Each array record uses the ads.txt record ID as it's key. |
Domain Adstxt Array Records
| tag: | string 16 character tag used with the record ID to identify the record. |
| type: | string data, variable, comment or collaborator. |
| name: | string For data type, the domain name for the record. For variable type, either contact, subdomain or inventorypartnerdomain. For group type, the name of the group. |
| publisher: | string (data type only) Publisher ID. |
| relationship: | string (data type only) DIRECT or RESELLER. |
| certification: | string (data type only) Certification authority ID. |
| value: | string (variable type only) For contact name, the contact details such as an email address or contact form URL. For subdomain name, the related subdomain such as blog.domain.com. For inventorypartnerdomain name, the related domain such as domain.com. |
| comment: | string (comment type only) Comment text. |
| records: | string (collaborator type only) A sub-array of the Domain Adstxt Array Records including all records for the collaborator group. |
# Example domain adstxt array
{
"tag": "abcdefgi01234567",
"type": "data",
"name": "google.com",
"publisher": "pub-0123456",
"relationship": "DIRECT",
"certification": "abcdef012345"
}
$api = atg_api('KEY', 'SECRET');
domain/adstxt/list
This function allows you to retrieve a list of all ads.txt records for a specific domain.
Successful response values
| success: | boolean true |
| adstxt: |
array Domain Adstxt Array. |
# Example request
curl https://adstxt.guru/api/1.0/domain/adstxt/list/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example successful response
{
"success": true,
"adstxt": {
"version": "0.0.1",
"records": {
"123": {
"tag": "abcdefgi01234567",
"type": "data",
"name": "google.com",
"publisher": "pub-0123456",
"relationship": "DIRECT",
"certification": "abcdef012345"
},
"124": {
"tag": "abcdefgi01234568",
"type": "variable",
"name": "contact",
"value": "email@domain.com"
},
"125": {
"tag": "abcdefgi01234569",
"type": "comment",
"comment": "Example comment."
},
"126": {
"tag": "abcdefgi01234560",
"type": "collaborator",
"name": "Example Group",
"records": {
"127": {
"tag": "abcdefgi01234561",
"type": "data",
"name": "google.com",
"publisher": "pub-0123457",
"relationship": "RESELLER",
"certification": "abcdef012345"
}
}
}
}
}
}
$api = atg_api('KEY', 'SECRET');
domain/adstxt/add
This function allows you to add a new ads.txt record.
Parameters
| domain: | integer (required) Numeric ID of domain. |
| type: | string (required) data, variable or comment. |
| name: | string (required for data and variable types) For data type, the domain name for the record. For variable type, either contact, subdomain or inventorypartnerdomain. |
| publisher: | string (required for data type) Publisher ID. |
| relationship: | string (required for data type) DIRECT or RESELLER. |
| certification: | string (data type only) Certification authority ID. |
| value: | string (required for variable type) For contact name, the contact details such as an email address or contact form URL. For subdomain name, the related subdomain such as blog.domain.com. For inventorypartnerdomain name, the related domain such as domain.com. |
| comment: | string (required for comment type) Comment text. |
Unsuccessful reasons
This function may return a reason value, or a reasons array containing multiple reasons.
| error: | A system error has occurred. |
| duplicate: | A duplicate ads.txt record already exists. |
| name-incomplete: | Name value not provided. |
| name-invalid: | Name value is invalid. |
| publisher-incomplete: | Publisher ID not provided. |
| publisher-invalid: | Publisher ID is invalid. |
| relationship-incomplete: | Relationship not provided. |
| relationship-invalid: | Relationship is invalid. |
| certification-invalid: | Certification ID is invalid. |
| value-incomplete: | Value not provided. |
| value-invalid: | Value is invalid. |
| comment-incomplete: | Comment not provided. |
| comment-invalid: | Comment is invalid. |
Successful response values
| success: | boolean true |
| id: | integer Numeric ID for ads.txt record. |
| tag: | string 16 character tag for ads.txt record. |
# Example request
curl https://adstxt.guru/api/1.0/domain/adstxt/add/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d type=data
-d name=google.com
-d publisher=pub-0123456
-d relationship=DIRECT
-d certification=abcdef012345
# Example invalid record response
{
"success": false,
"reasons": [
"name-invalid",
"publisher-invalid"
]
}
# Example successful response
{
"success": true,
"id": "123",
"tag": "abcdefgi01234567"
}
$api = atg_api('KEY', 'SECRET');
domain/adstxt/edit
This function allows you to edit an existing ads.txt record.
Parameters
| domain: | integer (required) Numeric ID of domain. |
| record: | integer (required) Numeric ID of ads.txt record. |
| tag: | string (required) 16 character tag for ads.txt record. |
| type: | string (required) data, variable or comment. |
| name: | string (required for data and variable types) For data type, the domain name for the record. For variable type, either contact, subdomain or inventorypartnerdomain. |
| publisher: | string (required for data type) Publisher ID. |
| relationship: | string (required for data type) DIRECT or RESELLER. |
| certification: | string (data type only) Certification authority ID. |
| value: | string (required for variable type) For contact name, the contact details such as an email address or contact form URL. For subdomain name, the related subdomain such as blog.domain.com. For inventorypartnerdomain name, the related domain such as domain.com. |
| comment: | string (required for comment type) Comment text. |
Unsuccessful reasons
This function may return a reason value, or a reasons array containing multiple reasons.
| id-invalid: | Invalid ads.txt record ID. |
| tag-invalid: | Invalid ads.txt record tag. |
| error: | A system error has occurred. |
| duplicate: | A duplicate ads.txt record already exists. |
| name-incomplete: | Name value not provided. |
| name-invalid: | Name value is invalid. |
| publisher-incomplete: | Publisher ID not provided. |
| publisher-invalid: | Publisher ID is invalid. |
| relationship-incomplete: | Relationship not provided. |
| relationship-invalid: | Relationship is invalid. |
| certification-invalid: | Certification ID is invalid. |
| value-incomplete: | Value not provided. |
| value-invalid: | Value is invalid. |
| comment-incomplete: | Comment not provided. |
| comment-invalid: | Comment is invalid. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/domain/adstxt/edit/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d record=123
-d tag=abcdefgi01234567
-d type=data
-d name=google.com
-d publisher=pub-0123456
-d relationship=DIRECT
-d certification=abcdef012345
# Example invalid record response
{
"success": false,
"reasons": [
"name-invalid",
"publisher-invalid"
]
}
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
domain/adstxt/remove
This function allows you to remove an existing ads.txt record.
Parameters
| domain: | integer (required) Numeric ID of domain. |
| record: | integer (required) Numeric ID of ads.txt record. |
| tag: | string (required) 16 character tag for ads.txt record. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/domain/adstxt/remove/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d record=123
-d tag=abcdefgi01234567
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
domain/adstxt/deduplicate
This function removes duplicate comment lines from a domain's ads.txt, keeping the first occurrence of each. Data records are not affected, and inherited collaborator records are left untouched. The version history is preserved, so the change can be rolled back.
Parameters
| domain: | integer (required) Numeric ID of domain. |
Successful response values
| success: | boolean true |
| removed_count: | integer Number of duplicate comment lines removed (0 if there were none). |
| version: | string The current ads.txt version number after the operation. |
# Example request
curl https://adstxt.guru/api/1.0/domain/adstxt/deduplicate/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example successful response
{
"success": true,
"removed_count": 2,
"version": "1.0.4"
}
$api = atg_api('KEY', 'SECRET');
domain/adstxt/delete_all
This function removes all of a domain's own ads.txt records in a single call. Inherited collaborator group blocks are kept. The version history is preserved, so the change can be rolled back.
Parameters
| domain: | integer (required) Numeric ID of domain. |
Successful response values
| success: | boolean true |
| deleted_count: | integer Number of records removed (0 if the domain had no own records). |
| version: | string The current ads.txt version number after the operation. |
# Example request
curl https://adstxt.guru/api/1.0/domain/adstxt/delete_all/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example successful response
{
"success": true,
"deleted_count": 12,
"version": "1.0.4"
}
$api = atg_api('KEY', 'SECRET');
domain/adstxt/import
This function allows you to import an ads.txt file.
Parameters
| domain: | integer (required) Numeric ID of domain. |
| import: | string (required) The contents of ads.txt file. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/domain/adstxt/import/
-d key=KEY
-d secret=SECRET
-d domain=1234
-d import=google.com%2C+pub-0123456%2C+DIRECT%2C+abcdef012345%0A%23+A+Comment%0Acontact%3Demail%40domain.com
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
domain/adstxt/download
This function allows you to download an ads.txt file.
Parameters
| domain: | integer (required) Numeric ID of domain. |
Successful response values
| success: | boolean true |
| adstxt: | string The content of the ads.txt file. |
# Example request
curl https://adstxt.guru/api/1.0/domain/adstxt/download/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example successful response
{
"success": true,
"adstxt": "# ATG-ABCDEFGU01234567\n# Version 0.0.1\ngoogle.com, pub-0123456, DIRECT, abcdef012345\ncontact=email@domain.com"
}
$api = atg_api('KEY', 'SECRET');
Group
The group functions allow you to manage the groups which would normally be managed under the Collaborate section of your ads.txt Guru account.
These functions give you complete control to add, edit and remove your groups. These functions are only available to users with the 'Ad Network' membership plan, although we currently only allow API access under that plan.
Group data is provided in what we refer to as the Group Array which includes the group values as outlined below.
Group Array
| id: | integer Numeric group ID. |
| tag: | string 16 character group (collaborator) tag. |
| name: | string The group name. |
| trusted: | integer 0 if group is not trusted, 1 if group is not trusted. |
| comment: | integer 0 if comments will not be included in generated ads.txt file, 1 if comments will be included. |
| synchronize: | integer 1 if automatic synchronization is enabled, 0 if not enabled. |
| discover: | integer 1 if group can be discovered using group (collaborator) tag, 0 if discovery is disabled. |
| approve: | integer 1 if domain requests should be automatically approved, 0 if domain requires require approval. |
| managerdomain: | string The group's manager domain, or an empty string if not set. Emitted as a MANAGERDOMAIN= line on domains the group is applied to in reseller relationship mode. |
# Example group array
{
"id": "1234",
"tag": "abcdefgi01234567",
"name": "Example Group",
"trusted": "0",
"comment": "1",
"synchronize": "0",
"discovery": "1",
"approve": "0",
"managerdomain": "ad-network.example"
}
$api = atg_api('KEY', 'SECRET');
group/list
This function allows you to retrieve a list of all groups under your account.
Successful response values
| success: | boolean true |
| groups: |
array An array of Group Arrays, each array record uses the group ID as it's key. |
# Example request
curl https://adstxt.guru/api/1.0/group/list/
-d key=KEY
-d secret=SECRET
# Example successful response
{
"success": true,
"groups": {
"1234" {
"id": "1234",
"tag": "abcdefgi01234567",
"name": "Example Group",
"trusted": "0",
"comment": "1",
"synchronize": "0",
"discovery": "1",
"approve": "0"
},
"1235" {
"id": "1235",
"tag": "abcdefgi01234568",
"name": "Another Group",
"trusted": "0",
"comment": "1",
"synchronize": "1",
"discovery": "1",
"approve": "1"
}
}
}
$api = atg_api('KEY', 'SECRET');
group/add
This function allows you to add a new group to your account.
Parameters
| name: | string (required) The name of the group. |
Unsuccessful reasons
| invalid: | Invalid name. |
| duplicate: | Group has already been added under this account. |
| conflict: | Group has already been added under another account. |
Successful response values
| success: | boolean true |
| group: |
array Group Array. |
# Example request
curl https://adstxt.guru/api/1.0/group/add/
-d key=KEY
-d secret=SECRET
-d name=Example Group
# Example duplicate domain response
{
"success": false,
"reason": "duplicate"
}
# Example successful response
{
"success": true,
"group": {
"id": "1234",
"tag": "abcdefgi01234567",
"name": "Example Group",
"trusted": "0",
"comment": "1",
"synchronize": "0",
"discovery": "1",
"approve": "0"
}
}
$api = atg_api('KEY', 'SECRET');
group/get
This function allows you to retrieve a specific group under your account.
Parameters
| group: | integer (required) Numeric ID of group you would like to retrieve. |
Successful response values
| success: | boolean true |
| group: |
array Group Array. |
# Example request
curl https://adstxt.guru/api/1.0/group/get/
-d key=KEY
-d secret=SECRET
-d group=1234
# Example successful response
{
"success": true,
"group": {
"id": "1234",
"tag": "abcdefgi01234567",
"name": "Example Group",
"trusted": "0",
"comment": "1",
"synchronize": "0",
"discovery": "1",
"approve": "0"
}
}
$api = atg_api('KEY', 'SECRET');
group/edit
This function allows you to edit a group under your account.
Parameters
| group: | integer (required) Numeric ID of group you would like to edit. |
| name: | string The new group name. |
| comment: | integer 0 if comments should not be included in generated ads.txt file, 1 if comments should be included. |
| synchronize: | integer 1 if automatic synchronization should be enabled, 0 if should not be enabled. |
| discover: | integer 1 if group should be discoverable using group (collaborator) tag, 0 if discovery should be disabled. |
| approve: | integer 1 if domain requests should be automatically approved, 0 if domain requires require approval. |
| managerdomain: | string Bare domain (e.g. ad-network.example) declared as this group's manager. When the group is applied to a domain in reseller relationship mode, a MANAGERDOMAIN= line pointing to this domain is added automatically. Pass an empty string to clear it. Omit the parameter to leave it unchanged. |
Unsuccessful reasons
| invalid: | Invalid name. |
| invalid-managerdomain: | The supplied manager domain is not a valid domain. |
| duplicate: | Group has already been added under this account. |
| conflict: | Group has already been added under another account. |
Successful response values
| success: | boolean true |
| group: |
array Group Array. |
# Example request
curl https://adstxt.guru/api/1.0/group/edit/
-d key=KEY
-d secret=SECRET
-d group=1234
-d comment=0
-d discovery=0
# Example successful response
{
"success": true,
"group": {
"id": "1234",
"tag": "abcdefgi01234567",
"name": "Example Group",
"trusted": "0",
"comment": "0",
"synchronize": "0",
"discovery": "0",
"approve": "0"
}
}
$api = atg_api('KEY', 'SECRET');
group/remove
This function allows you to remove a specific group under your account.
Parameters
| group: | integer (required) Numeric ID of group you would like to remove. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/group/remove/
-d key=KEY
-d secret=SECRET
-d group=1234
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
group/synchronize
This function allows you to provoke synchronization of a specific group under your account.
Parameters
| group: | integer (required) Numeric ID of group you would like to synchronize. |
Unsuccessful reasons
| error: | A system error has occurred. |
| nosuccess: | No domains were successfully synchronized. |
Successful response values
| success: | boolean true |
| success_count: | integer The number of domains which were successfully synchronized. |
| failed_count: | integer The number of domains which failed to be synchronized. |
# Example request
curl https://adstxt.guru/api/1.0/group/synchronize/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example 'nosuccess' response
{
"success": false,
"reason": "nosuccess",
"failed_count": "5"
}
# Example successful response
{
"success": true,
"success_count": "5",
"failed_count": "0"
}
# Example partially successful response
{
"success": true,
"success_count": "2",
"failed_count": "3"
}
$api = atg_api('KEY', 'SECRET');
Group Domain
The group domain functions allow you to manage which domains the group can collaborate with, you can also invite new domains to a group using domain tags.
These functions do not allow you to manage requests from domains, these are managed with the Group Request functions. For clarification, a domain can request collaboration with a group, whereas a group can invite a domain to collaborate.
Domain data is provided in what we refer to as the Group Domain Array which includes the domain relationship values as outlined below, this should not be confused with the Domain Array or Group Array.
Group Domain Array
| id: | integer Numeric group ID. |
| domain: | string The domain name. |
| flex: | array An array of values for this group's flex records. |
| approved: | integer 1 if collaboration with this domain has been approved, 0 if collaboration has not yet been approved. |
# Example group domain array
{
"id": "1234",
"domain": "domain.com",
"flex": {
"1-abcdefgi01234567": "pub-0123456"
},
"approved": "1"
}
$api = atg_api('KEY', 'SECRET');
group/domain/list
This function allows you to list the domains which are collaborating with this group.
Parameters
| group: | integer (required) Numeric ID of group. |
Successful response values
| success: | boolean true |
| domains: | array An array of Group Domain Arrays, each array record uses the request ID as it's key. |
# Example request
curl https://adstxt.guru/api/1.0/group/domain/list/
-d key=KEY
-d secret=SECRET
-d group=1234
# Example successful response
{
"success": true,
"groups": {
"123": {
"id": "123",
"domain": "domain.com",
"flex": {
"1-abcdefgi01234567": "pub-0123456"
},
"approved": "1"
},
"124": {
"id": "124",
"domain": "example.com",
"flex": {},
"approved": "0"
},
}
}
$api = atg_api('KEY', 'SECRET');
group/domain/invite
This function allows you to invite a domain to collaborate using the domain tag. All requests require approval by the domain.
Domain tags are only accessible to the domain owner, they must in turn share their domain tag with you to enable you to submit an invite.
Parameters
| group: | integer (required) Numeric ID of group. |
| tag: | string (required) 16 character domain tag. |
| message: | string A message to help the domain determine your eligibility to collaborate, maximum length is 255 characters, usage of certain characters/symbols is restricted. |
Unsuccessful reasons
| invalid-tag: | Collaborator tag is invalid. |
| invalid-message: | Invalid message, either it exceeds 255 characters or contains restricted characters/symbols. |
| duplicate: | Duplicate request, collaboration with this domain already exists or has already been requested. |
| limit: | Maximum publishers limit reached. |
Successful response values
| success: | boolean true |
| invite: | array Group Domain Array. |
# Example request
curl https://adstxt.guru/api/1.0/group/domain/invite/
-d key=KEY
-d secret=SECRET
-d group=1234
-d tag=abcdefgi01234567
-d message=Request+from+Ad+Network+as+discussed+with%2C+john%40example.com.
# Example invalid tag response
{
"success": false,
"reason": "invalid-tag"
}
# Example successful response
{
"success": true,
"invite": {
"id": "123",
"domain": "domain.com",
"flex": {},
"approved": "0"
}
}
$api = atg_api('KEY', 'SECRET');
group/domain/edit
This function allows you to edit the flex record publisher ID values for a collaborating domain.
Parameters
| group: | integer (required) Numeric ID of group. |
| domain: | integer (required) Numeric ID of group domain invite. |
| flex-ID-TAG: | string (required) This field must be submitted for each flex record which exists under this group, the ID and TAG values are taken from the Group Adstxt Array. |
Unsuccessful reasons
| ID-TAG: | A separate reason will be returned for any invalid flex record values, the reason will be defined as the ID and TAG as taken from the Group Adstxt Array. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/group/domain/edit/
-d key=KEY
-d secret=SECRET
-d group=1234
-d domain=123
-d flex-1-abcdefgi01234567=pub-0123456
# Example unsuccessful response
{
"success": false,
"reasons": [
"1-abcdefgi01234567"
]
}
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
group/domain/relationship
This function sets how a group's records render on one of its collaborating domains. The change is applied immediately, so the domain's ads.txt reflects it on the next read.
| inherit: | Each record renders exactly as authored on the group (default). |
| direct: | Every data record is forced to DIRECT on this domain. |
| reseller: | Every data record is forced to RESELLER on this domain, and the group's manager domain (if set) is added as a MANAGERDOMAIN= line. |
Parameters
| group: | integer (required) Numeric ID of group. |
| domain: | integer (required) Numeric ID of the domain (as returned by group/domain/list). |
| relationship: | string (required) One of inherit, direct or reseller. |
Unsuccessful reasons
| invalid: | Invalid group, domain, or relationship value. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/group/domain/relationship/
-d key=KEY
-d secret=SECRET
-d group=1234
-d domain=123
-d relationship=reseller
# Example unsuccessful response
{
"success": false,
"reason": "invalid"
}
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
group/domain/remove
This function allows you to remove a domain to discontinue collaboration.
Parameters
| group: | integer (required) Numeric ID of group. |
| domain: | integer (required) Numeric ID of group domain invite. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/group/domain/remove/
-d key=KEY
-d secret=SECRET
-d group=1234
-d domain=123
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
Group Request
The group request functions allow you to view, approve and decline requests you have received to collaborate with domains.
These functions do not allow you to manage existing domain collaboration relationships, these are managed with the Group Domain functions. For clarification, a domain can request collaboration with a group, whereas a group can invite a domain to collaborate.
Request data is provided in what we refer to as the Group Request Array which includes the request relationship values as outlined below, this should not be confused with the Domain Array or Group Array. The Group Request Array follows the same format as the Group Domain Array with the addition of the message value.
Group Request Array
| id: | integer Numeric group ID. |
| domain: | string The domain name. |
| approved: | integer 1 if collaboration with this domain has been approved, 0 if collaboration has not yet been approved. |
| message: | string A message from the domain to help you determine the domain's eligibility to collaborate. |
# Example group request array
{
"id": "1234",
"domain": "domain.com",
"approved": "1",
"message": "My publisher account username is ABC123."
}
$api = atg_api('KEY', 'SECRET');
group/request/list
This function allows you to list the requests you have received to collaborate with domains.
Parameters
| group: | integer (required) Numeric ID of group. |
Successful response values
| success: | boolean true |
| requests: | array An array of Group Request Arrays, each array record uses the request ID as it's key. |
# Example request
curl https://adstxt.guru/api/1.0/group/request/list/
-d key=KEY
-d secret=SECRET
-d domain=1234
# Example successful response
{
"success": true,
"requests": {
"123": {
"id": "123",
"group": "domain.com",
"approved": "0",
"message": "My publisher account username is ABC123."
},
"124": {
"id": "124",
"group": "example.com",
"approved": "0",
"message": ""
},
}
}
$api = atg_api('KEY', 'SECRET');
group/request/approve
This function allows you to approve a request. Once approved the request becomes a group domain which can be managed with the Group Domain functions.
Parameters
| group: | integer (required) Numeric ID of group. |
| request: | string (required) Numeric ID of request. |
Unsuccessful reasons
| limit: | Maximum publishers limit reached. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/group/request/approve/
-d key=KEY
-d secret=SECRET
-d group=1234
-d request=123
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
group/request/decline
This function allows you to decline a request.
Parameters
| group: | integer (required) Numeric ID of group. |
| request: | string (required) Numeric ID of request. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/group/request/decline/
-d key=KEY
-d secret=SECRET
-d group=1234
-d request=123
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
Group Adstxt
The group adstxt functions allow you to manage your ads.txt records, for example to add new ads.txt records or to download your ads.txt file.
Adstxt data is provided in what we refer to as the Group Adstxt Array which includes all your ads.txt records in array format. The Group Adstxt Array is fundamentally the same as the Domain Adstxt array, with the exception that 'collaborator' type records will not be included.
Group Adstxt Array
| version: | version The numeric version number, e.g. 0.0.1. |
| records: | array An array of ads.txt records, as outlined below. Each array record uses the ads.txt record ID as it's key. |
Group Adstxt Array Records
| tag: | string 16 character tag used with the record ID to identify the record. |
| type: | string data, flex, variable or comment. |
| name: | string For data and flex types, the domain name for the record. For variable type, either contact, subdomain or inventorypartnerdomain. For group type, the name of the group. |
| publisher: | string (data type only) Publisher ID. |
| relationship: | string (data and flex types only) DIRECT or RESELLER. |
| certification: | string (data and flex types only) Certification authority ID. |
| value: | string (variable type only) For contact name, the contact details such as an email address or contact form URL. For subdomain name, the related subdomain such as blog.domain.com. For inventorypartnerdomain name, the related domain such as domain.com. |
| comment: | string (comment type only) Comment text. |
# Example group adstxt array
{
"tag": "abcdefgi01234567",
"type": "data",
"name": "google.com",
"publisher": "pub-0123456",
"relationship": "DIRECT",
"certification": "abcdef012345"
}
$api = atg_api('KEY', 'SECRET');
group/adstxt/list
This function allows you to retrieve a list of all ads.txt records for a specific group.
Successful response values
| success: | boolean true |
| adstxt: |
array Group Adstxt Array. |
# Example request
curl https://adstxt.guru/api/1.0/group/adstxt/list/
-d key=KEY
-d secret=SECRET
-d group=1234
# Example successful response
{
"success": true,
"adstxt": {
"version": "0.0.1",
"records": {
"123": {
"tag": "abcdefgi01234567",
"type": "data",
"name": "google.com",
"publisher": "pub-0123456",
"relationship": "DIRECT",
"certification": "abcdef012345"
},
"124": {
"tag": "abcdefgi01234568",
"type": "variable",
"name": "contact",
"value": "email@domain.com"
},
"125": {
"tag": "abcdefgi01234569",
"type": "comment",
"comment": "Example comment."
}
}
}
}
$api = atg_api('KEY', 'SECRET');
group/adstxt/add
This function allows you to add a new ads.txt record.
Parameters
| group: | integer (required) Numeric ID of group. |
| type: | string (required) data, flex, variable or comment. |
| name: | string (required for data, flex and variable types) For data and flex type, the domain name for the record. For variable type, either contact, subdomain or inventorypartnerdomain. |
| publisher: | string (required for data type) Publisher ID. |
| relationship: | string (required for data and flex types) DIRECT or RESELLER. |
| certification: | string (data and flex types only) Certification authority ID. |
| value: | string (required for variable type) For contact name, the contact details such as an email address or contact form URL. For subdomain name, the related subdomain such as blog.domain.com. For inventorypartnerdomain name, the related domain such as domain.com. |
| comment: | string (required for comment type) Comment text. |
Unsuccessful reasons
This function may return a reason value, or a reasons array containing multiple reasons.
| error: | A system error has occurred. |
| duplicate: | A duplicate ads.txt record already exists. |
| name-incomplete: | Name value not provided. |
| name-invalid: | Name value is invalid. |
| publisher-incomplete: | Publisher ID not provided. |
| publisher-invalid: | Publisher ID is invalid. |
| relationship-incomplete: | Relationship not provided. |
| relationship-invalid: | Relationship is invalid. |
| certification-invalid: | Certification ID is invalid. |
| value-incomplete: | Value not provided. |
| value-invalid: | Value is invalid. |
| comment-incomplete: | Comment not provided. |
| comment-invalid: | Comment is invalid. |
Successful response values
| success: | boolean true |
| id: | integer Numeric ID for ads.txt record. |
| tag: | string 16 character tag for ads.txt record. |
# Example request
curl https://adstxt.guru/api/1.0/group/adstxt/add/
-d key=KEY
-d secret=SECRET
-d group=1234
-d type=data
-d name=google.com
-d publisher=pub-0123456
-d relationship=DIRECT
-d certification=abcdef012345
# Example invalid record response
{
"success": false,
"reasons": [
"name-invalid",
"publisher-invalid"
]
}
# Example successful response
{
"success": true,
"id": "123",
"tag": "abcdefgi01234567"
}
$api = atg_api('KEY', 'SECRET');
group/adstxt/edit
This function allows you to edit an existing ads.txt record.
Parameters
| group: | integer (required) Numeric ID of group. |
| record: | integer (required) Numeric ID of ads.txt record. |
| tag: | string (required) 16 character tag for ads.txt record. |
| type: | string (required) data, flex, variable or comment. |
| name: | string (required for data, flex and variable types) For data and flex type, the domain name for the record. For variable type, either contact, subdomain or inventorypartnerdomain. |
| publisher: | string (required for data type) Publisher ID. |
| relationship: | string (required for data and flex type) DIRECT or RESELLER. |
| certification: | string (data and flex type only) Certification authority ID. |
| value: | string (required for variable type) For contact name, the contact details such as an email address or contact form URL. For subdomain name, the related subdomain such as blog.domain.com. For inventorypartnerdomain name, the related domain such as domain.com. |
| comment: | string (required for comment type) Comment text. |
Unsuccessful reasons
This function may return a reason value, or a reasons array containing multiple reasons.
| id-invalid: | Invalid ads.txt record ID. |
| tag-invalid: | Invalid ads.txt record tag. |
| error: | A system error has occurred. |
| duplicate: | A duplicate ads.txt record already exists. |
| name-incomplete: | Name value not provided. |
| name-invalid: | Name value is invalid. |
| publisher-incomplete: | Publisher ID not provided. |
| publisher-invalid: | Publisher ID is invalid. |
| relationship-incomplete: | Relationship not provided. |
| relationship-invalid: | Relationship is invalid. |
| certification-invalid: | Certification ID is invalid. |
| value-incomplete: | Value not provided. |
| value-invalid: | Value is invalid. |
| comment-incomplete: | Comment not provided. |
| comment-invalid: | Comment is invalid. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/group/adstxt/edit/
-d key=KEY
-d secret=SECRET
-d group=1234
-d record=123
-d tag=abcdefgi01234567
-d type=data
-d name=google.com
-d publisher=pub-0123456
-d relationship=DIRECT
-d certification=abcdef012345
# Example invalid record response
{
"success": false,
"reasons": [
"name-invalid",
"publisher-invalid"
]
}
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
group/adstxt/remove
This function allows you to remove an existing ads.txt record.
Parameters
| group: | integer (required) Numeric ID of group. |
| record: | integer (required) Numeric ID of ads.txt record. |
| tag: | string (required) 16 character tag for ads.txt record. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/group/adstxt/remove/
-d key=KEY
-d secret=SECRET
-d group=1234
-d record=123
-d tag=abcdefgi01234567
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
group/adstxt/import
This function allows you to import an ads.txt file.
Parameters
| group: | integer (required) Numeric ID of group. |
| import: | string (required) The contents of ads.txt file. |
Successful response values
| success: | boolean true |
# Example request
curl https://adstxt.guru/api/1.0/group/adstxt/import/
-d key=KEY
-d secret=SECRET
-d group=1234
-d import=google.com%2C+pub-0123456%2C+DIRECT%2C+abcdef012345%0A%23+A+Comment%0Acontact%3Demail%40domain.com
# Example successful response
{
"success": true
}
$api = atg_api('KEY', 'SECRET');
group/adstxt/download
This function allows you to download an ads.txt file.
Parameters
| group: | integer (required) Numeric ID of group. |
Successful response values
| success: | boolean true |
| adstxt: | string The content of the ads.txt file. |
# Example request
curl https://adstxt.guru/api/1.0/group/adstxt/download/
-d key=KEY
-d secret=SECRET
-d group=1234
# Example successful response
{
"success": true,
"adstxt": "# ATG-ABCDEFGU01234567\n# Version 0.0.1\ngoogle.com, pub-0123456, DIRECT, abcdef012345\ncontact=email@domain.com"
}
$api = atg_api('KEY', 'SECRET');
Validate
The validate functions allow you to validate ads.txt files programmatically, either by providing the URL of an ads.txt file, or by providing the contents of an ads.txt file directly.
Usage of this function is currently unrestricted, however we reserve the right to place limitations on this function. Please contact us if you intend to use this function intensively.
Validation results for each line of the ads.txt file are provided in what we refer to as the Adstxt Validation Array which includes the values as outlined below.
Adstxt Validation Array
| line: | integer ads.txt file line number. |
| type: | string The line type, either data, variable, comment, blank, invalid or unknown. |
| variable: | string (variable type only) contact, subdomain or inventorypartnerdomain. |
| duplicate: | array An array containing line numbers of matching duplicate records. |
| data: | string The contents of the line. |
| error: | array An array containing error reasons as outlined below. Errors are considered serious failures which must be resolved. |
| warning: | array An array containing warning reasons as outlined below. Warnings are points of concern which should be checked. |
| notice: | array An array containing notice reasons as outlined below. Notices highlight ways to improve the ads.txt formatting. |
| valid: | interger 1 if the record is valid, or 0 if the record has at least one error, warning or notice. |
Error reasons
| line-invalid: | Line is invalid and failed all validation. |
| data-format: | Data record is formatted incorrectly (less than 3 or more than 4 parts). |
| data-domain-invalid: | Data record domain is invalid. |
| data-publisher-invalid: | Data record publisher ID is invalid. |
| data-relationship-invalid: | Data record relationship value is invalid. |
| data-certification-invalid: | Data record certification ID is invalid. |
| data-certification-incorrect: | Data record certification ID is incorrect. |
Warning reasons
| data-domain-invalid: | Data record domain may be invalid. |
| variable-name-invalid: | Variable name is invalid, must be 'CONTACT', 'SUBDOMAIN' or 'INVENTORYPARTNERDOMAIN'. |
| variable-contact-invalid: | Variable contact value is invalid. |
| variable-subdomain-invalid | Variable subdomain value is invalid. |
| variable-inventorypartnerdomain-invalid | Variable inventorypartnerdomain value is invalid. |
Notice reasons
| line-inline-comment: | Line contains inline comment. |
| line-whitespace: | Line contains unnecessary whitespace. |
| data-domain-case: | Data record domain value contains uppercase characters. |
| data-domain-whitespace: | Data record domain value contains unnecessary whitespace. |
| data-publisher-whitespace: | Data record publisher ID contains unnecessary whitespace. |
| data-relationship-case: | Data record relationship value contains lowercase characters. |
| data-relationship-whitespace: | Data record relationship value contains unnecessary whitespace. |
| data-certification-whitespace: | Data record certification ID value contains unnecessary whitespace. |
| comment-compatibility: | Comment contains unusual characters/symbols, consider removing for compatibility. |
# Example adstxt validation array
{
"line": 1,
"type": "data",
"duplicate": [
"4",
"17"
],
"data": "domaincom , 1234567, DIREC, abcdefghijk",
"error": [
"data-domain-invalid",
"data-relationship-invalid"
],
"warning": [],
"notice": [
"data-domain-whitespace"
],
"valid": "0"
}
$api = atg_api('KEY', 'SECRET');
validate/adstxt
This function allows you to validate a raw ads.txt file, either by providing the URL of an ads.txt file, or by providing the contents of an ads.txt file directly.
Usage of this function is currently unrestricted, however we reserve the right to place limitations on this function. Please contact us if you intend to use this function intensively.
Parameters
| data: | string The contents of an ads.txt file. Note, this method is not suitable for large ads.txt files. |
| url: | string (recommended method) The full URL of an ads.txt file, e.g. http://domain.com/ads.txt |
Unsuccessful reasons
| error: | A system error has occurred. |
| empty-file: | The ads.txt file is empty or contains only whitespace. |
| toolarge: | ads.txt file is greater the 1 MB, the maximum size supported. |
| url-invalid: | An invalid URL was provided. |
| url-connect: | Connection to URL failed. |
Successful response values
Note, the ads.txt file is considered valid if the error_count value is zero.
| success: | boolean true |
| error_count: | integer The total number of errors detected. |
| warning_count: | integer The total number of warnings detected. |
| notice_count: | integer The total number of notices detected. |
| valid_count: | integer The total number of valid lines detected. |
| adstxt: | array An array of Adstxt Validation Arrays, each array record uses the line number as it's key. |
# Example request
curl https://adstxt.guru/api/1.0/validate/adstxt/
-d key=KEY
-d secret=SECRET
-d url=http://domain.com/ads.txt
# Example successful response
{
"success": true,
"error_count": 1,
"warning_count": 0,
"notice_count": 1,
"valid_count": 0,
"adstxt": {
"1": {
"line": 1,
"type": "data",
"duplicate": [],
"data": "example.com, abcdefg, DIRECT",
"error": [],
"warning": [],
"notice": [],
"valid": "1"
},
"2": {
"line": 2,
"type": "unknown",
"duplicate": [],
"data": " test",
"error": [
"line-invalid"
],
"warning": [],
"notice": [
"line-whitespace"
],
"valid": "0"
}
}
}
$api = atg_api('KEY', 'SECRET');
Compare
The compare functions allow you to verify whether specific ads.txt records are included in the ads.txt files of multiple domains. This functionality can be used to ensure your publishers have implemented specific ads.txt records.
Usage of this function is currently unrestricted, however we reserve the right to place limitations on this function. Please contact us if you intend to use this function intensively.
Comparison results are provided for each domain which is provided in what we refer to as the Adstxt Comparison Array which includes the values as outlined below.
Adstxt Comparison Array
| domain: | string The domain name which was provided. |
| id: | string The ID for the domain (if provided). |
| url: | string The URL which was checked - this is the domain name, including the protocol used and the 'ads.txt' filename. |
| status: | string success, missing or failed. |
| missing: | array An array containing all missing records. |
| error: | string An error message, if applicable. |
| reason: | string A detailed explanation for the error message, if applicable. |
# Example adstxt comparison array
{
"domain": "example.com",
"id": "CUSTOM-ID",
"url": "http://example.com/ads.txt",
"status": "missing",
"missing": [
"domain.com, 123456, DIRECT"
],
"error": "",
"reason": ""
}
$api = atg_api('KEY', 'SECRET');
compare/adstxt
This function allows you to verify whether specific ads.txt records are included in the ads.txt files of multiple domains.
Usage of this function is currently unrestricted, however we reserve the right to place limitations on this function. Please contact us if you intend to use this function intensively.
Parameters
| adstxt: | string The ads.txt records which you would like to check are present on the specified domains, formatted as a standard ads.txt file. Only data records will be compared - variables and comments will be ignored. |
| domains: | string A list of domains to check. Each domain can include a protocol (http or https), but should not include a trailing slash or filename. A unique ID can be included after each domain sepearated by a comma - this ID is then returned in the results to assist with processing. |
Unsuccessful reasons
| adstxt-toolarge: | ads.txt input must be less than 1 MB. |
| adstxt-error: | Unable to process ads.txt input. |
| domains-toolarge: | Domains input must be less than 1 MB. |
| domains-error: | Unable to process domains input. |
| domains-limit: | Domains input contains too many domains. |
Successful response values
| success: | boolean true |
| matched_count: | integer The total number of domains which matched all records. |
| partial_count: | integer The total number of domains which were missing some or all records. |
| failed_count: | integer The total number of domains with errors such as connection errors or non-existent ads.txt files. |
| results: | array An array of Adstxt Comparision Arrays for each domain being checked. |
# Example request
curl https://adstxt.guru/api/1.0/compare/adstxt/
-d key=KEY
-d secret=SECRET
-d adstxt=domain.com, 12345, DIRECT
-d domains=example.com,EXAMPLE-ID\n
http://www.missing.com\n
subdomain.failed.com
# Example successful response
{
"success": true,
"matched_count": 1,
"partial_count": 1,
"failed_count": 1,
"results": [
{
"domain": "example.com",
"id": "EXAMPLE-ID",
"url": "https://example.com/ads.txt",
"status": "success",
"missing": [],
"error": "",
"reason": ""
},
{
"domain": "http://missing.com",
"id": "ID",
"url": "https://www.missing.com/ads.txt",
"status": "missing",
"missing": [
"domain.com, 12345, DIRECT"
],
"error": "",
"reason": ""
},
{
"domain": "subdomain.failed.com",
"id": "",
"url": "https://subdomain.failed.com/ads.txt",
"status": "failed",
"missing": [],
"error": "Connection error",
"reason": "Your URL returned a 404 File Not Found error indicating an ads.txt file can not be found."
}
]
}
$api = atg_api('KEY', 'SECRET');