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, and a 400 code will be returned if the request was invalid.

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.
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');

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.
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",
    "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.

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": "0",
        "comment": "1",
        "synchronize": "0",
        "discovery": "1"
    }
}
$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 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.

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 or subdomain.
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.
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 or subdomain.
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.
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 or subdomain.
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.
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/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.
# Example group array

{
    "id": "1234",
    "tag": "abcdefgi01234567",
    "name": "Example Group",
    "trusted": "0",
    "comment": "1",
    "synchronize": "0",
    "discovery": "1",
    "approve": "0"
}
$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.

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/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.
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",
    "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",
            "approved": "1"
        },
        "124": {
            "id": "124",
            "domain": "example.com",
            "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",
        "approved": "0"
    }
}
$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, variable or comment.
name: string
For data type, the domain name for the record.
For variable type, either contact or subdomain.
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.
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, 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 or subdomain.
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.
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, 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 or subdomain.
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.
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');

Crawl

The crawl functions allow you to retrieve, process and verify ads.txt records from third-party domains, allowing for simple or comprehensive analysis of ads.txt files.

This function is currently being fine-tuned and documentation will be provided in due course.

$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 or subdomain.
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.

Warning reasons

data-domain-invalid: Data record domain may be invalid.
variable-name-invalid: Variable name is invalid, must be 'CONTACT' or 'SUBDOMAIN'.
variable-contact-invalid: Variable contact value is invalid.
variable-subdomain-invalid Variable subdomain value is invalid.

Notice reasons

line-inline-comment: Line contains inline comment, consider moving to own line for compatibility.
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-relationship-invalid"
    ],
    "warning": [],
    "notice": [
        "data-domain-whitespace"
    ]
}
$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.
toolarge: ads.txt file is greater the 256 kB, 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');