Overview
API Concepts Manage API Key
Internet Data
DNSIQ® WHOISIQ™ SSL Certificates Blacklist Lookup Host Attributes
Attack Analytics
Newly Observed Domains Newly Observed Hosts Malware Phishing Scam Content
Digital Footprint
Global Inventory API Global Inventory Schema
Coming Soon
Enrich
PassiveTotal
Actions Artifact Enrichment Exposed Services Monitor Project SSL Certificates Tag Artifact Trackers Host Attributes Passive DNS Whois Bulk Enrichment
Additional Resources
Workspace Management API
RiskIQ.com

Artifact

 

What It Looks Like

Bulk Create Artifacts

Create artifacts in bulk.

Curl Example

 # Multiline command to add two queries to a project 
-XPUT -H "Content-Type: application/json" --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/pt/v2/artifact/bulk' \ --data '{"artifacts":[ {"project": "f083816f-9769-16cb-4660-4b389dc3ae67", "query": "example.org"}, {"project": "f083816f-9769-16cb-4660-4b389dc3ae67", "query": "passivetotal.org", "tags": ["foo"]} ]}'

Parameters

Field Field Type Description
artifacts Object[] a list of dictionaries that match the /pt/v2/artifact interface (has query, type, tags, and project fields per dictionary)
project UUID the project id the artifact will live on
query String the actual artifact query (passivetotal.org, 8.8.8.8, etc).
type (optional)String the type of the artifact (domain, ip, etc), or inferred by query string if domain or ip (optional).
Available types: ip, wildcard, email, domain, component, hash_md5, hash_sha1, hash_sha256, cookies_name, cookies_domain, url, certificate_serialnumber, certificate_sha1, certificate_issuercommonname, certificate_issueralternativename, certificate_subjectcommonname, certificate_subjectalternativename, certificate_issuerorganizationname, certificate_subjectorganizationname, certificate_issuerorganizationunit, certificate_subjectorganizationunit, certificate_issuerstreetaddress, certificate_subjectstreetaddress, certificate_issuerlocalityname, certificate_subjectlocalityname, certificate_issuerstateorprovincename, certificate_subjectstateorprovincename, certificate_issuercountry, certificate_subjectcountry, certificate_issuerserialnumber, certificate_subjectserialnumber
tags (optional)String[] the tags the new artifact will have

JSON Request

{
    "artifacts": [
        {
            "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
            "query": "example.org"
        },
        ...
        {
            "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
            "query": "passivetotal.org",
            "tags": ["foo"]
        },
        {
            "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
            "query": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
            "type": "certificate_sha1"
        }
    ]
}
			

Sample Response

{
    "838439d8-d291-4e20-dec8-05c8f7f7ba57": {
        "global_tags": [
            "registered"
        ],
        "system_tags": [
            "registered"
        ],
        "monitor": false,
        "query": "example.org",
        "tag_meta": {},
        "type": "domain",
        "creator": "sim.gretina@example.org",
        "organization": "eswing",
        "links": {
            "self": "/pt/v2/artifact?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57",
            "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67",
            "tag": "/pt/v2/artifact/tag?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57"
        },
        "guid": "838439d8-d291-4e20-dec8-05c8f7f7ba57",
        "user_tags": [],
        "owner": "eswing",
        "success": true,
        "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
        "monitorable": true,
        "created": "2017-04-15T00:18:06.580000"
    },
    ...
    ,"35012697-41b2-f6ac-9f3f-ed45d6464a65": {
        "global_tags": [
            "registered",
            "foo"
        ],
        "system_tags": [
            "registered"
        ],
        "monitor": false,
        "query": "passivetotal.org",
        "tag_meta": {
            "foo": {
                "creator": "sim.gretina@example.org",
                "created_at": "2017-04-13T01:34:44.570000"
            }
        },
        "type": "domain",
        "creator": "sim.gretina@example.org",
        "organization": "eswing",
        "links": {
            "self": "/pt/v2/artifact?artifact=35012697-41b2-f6ac-9f3f-ed45d6464a65",
            "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67",
            "tag": "/pt/v2/artifact/tag?artifact=35012697-41b2-f6ac-9f3f-ed45d6464a65"
        },
        "guid": "35012697-41b2-f6ac-9f3f-ed45d6464a65",
        "user_tags": [
            "foo"
        ],
        "owner": "eswing",
        "success": true,
        "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
        "monitorable": true,
        "created": "2017-04-17T19:58:26.765448"
    }
}
			

Bulk Delete Artifacts

Delete artifacts in bulk.

Curl Example

curl -XDELETE -H "Content-Type: application/json" --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/pt/v2/account/artifact/bulk'  --data '{"artifacts":["35012697-41b2-f6ac-9f3f-ed45d6464a65", "838439d8-d291-4e20-dec8-05c8f7f7ba57"]}'

Parameters

Field Field Type Description
artifactsUUID[] the artifact ids to delete

JSON Request

{
    "artifacts": [
        "35012697-41b2-f6ac-9f3f-ed45d6464a65",
        "838439d8-d291-4e20-dec8-05c8f7f7ba57"
    ]
}
			

Sample Response

{
    "838439d8-d291-4e20-dec8-05c8f7f7ba57": {
        "created": "2017-04-15T00:18:06.580000",
        "monitor": true,
        "owner": "eswing",
        "success": true,
        "type": "domain",
        "user_tags": [
            "malware",
            "scammer"
        ],
        "creator": "sim.gretina@example.org",
        "guid": "838439d8-d291-4e20-dec8-05c8f7f7ba57",
        "organization": "eswing",
        "global_tags": [
            "registered",
            "malware",
            "scammer"
        ],
        "system_tags": [
            "registered"
        ],
        "monitorable": true,
        "query": "example.org",
        "links": {
            "tag": "/pt/v2/artifact/tag?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57",
            "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67",
            "self": "/pt/v2/artifact?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57"
        },
        "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
        "tag_meta": {
            "malware": {
                "created_at": "2017-04-17T20:08:31.156000",
                "creator": "sim.gretina@example.org"
            },
            "scammer": {
                "created_at": "2017-04-17T20:08:31.156000",
                "creator": "sim.gretina@example.org"
            }
        }
    },
    "35012697-41b2-f6ac-9f3f-ed45d6464a65": {
        "created": "2017-04-17T19:58:26.765000",
        "monitor": true,
        "owner": "eswing",
        "success": true,
        "type": "domain",
        "user_tags": [
            "phisher",
            "scammer"
        ],
        "creator": "sim.gretina@example.org",
        "guid": "35012697-41b2-f6ac-9f3f-ed45d6464a65",
        "organization": "eswing",
        "global_tags": [
            "registered",
            "phisher",
            "scammer"
        ],
        "system_tags": [
            "registered"
        ],
        "monitorable": true,
        "query": "passivetotal.org",
        "links": {
            "tag": "/pt/v2/artifact/tag?artifact=35012697-41b2-f6ac-9f3f-ed45d6464a65",
            "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67",
            "self": "/pt/v2/artifact?artifact=35012697-41b2-f6ac-9f3f-ed45d6464a65"
        },
        "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
        "tag_meta": {
            "scammer": {
                "created_at": "2017-04-17T20:08:30.929000",
                "creator": "sim.gretina@example.org"
            },
            "phisher": {
                "created_at": "2017-04-17T20:08:30.929000",
                "creator": "sim.gretina@example.org"
            }
        }
    }
}
			

Error Response

{
    "'838439d8-d291-4e20-dec8-05c8f7f7ba57'": {
        "success": false,
        "error": "no artifact with that ID"
    },
    "'35012697-41b2-f6ac-9f3f-ed45d6464a65'": {
        "success": false,
        "error": "no artifact with that ID"
    }
}
			

Bulk Update Artifacts

Perform artifact updates in bulk.

Curl Example

 # Multiline command to add update two artifacts curl 
-XPOST -H "Content-Type: application/json" --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/pt/v2/artifact/bulk' \ --data '{"artifacts":[ {"artifact": "35012697-41b2-f6ac-9f3f-ed45d6464a65", "monitor": true, "tags": ["phisher", "scammer"]}, {"artifact": "838439d8-d291-4e20-dec8-05c8f7f7ba57", "monitor": true, "tags": ["scammer", "malware"]} ]}'

Parameters

Field Field Type Description
artifactsObject[] a list of dictionaries which match the fields for the /pt/v2/artifact (artifact, monitor, tags)
artifactUUID the artifact id to update
monitor (optional)Boolean whether to monitor the artifact
tags (optional)String[] sets the artifact's tags to this list

JSON Request

{
    "artifacts": [
        {
            "artifact": "35012697-41b2-f6ac-9f3f-ed45d6464a65",
            "monitor": true,
            "tags": [
                "phisher",
                "scammer"
            ]
        },
        {
            "artifact": "838439d8-d291-4e20-dec8-05c8f7f7ba57",
            "monitor": true,
            "tags": [
                "scammer",
                "malware"
            ]
        }
    ]
}
			

Sample Response

{
    "838439d8-d291-4e20-dec8-05c8f7f7ba57": {
        "global_tags": [
            "registered",
            "malware",
            "scammer"
        ],
        "system_tags": [
            "registered"
        ],
        "monitor": true,
        "query": "example.org",
        "tag_meta": {
            "scammer": {
                "creator": "sim.gretina@example.org",
                "created_at": "2017-04-17T20:08:31.156000"
            },
            "malware": {
                "creator": "sim.gretina@example.org",
                "created_at": "2017-04-17T20:08:31.156000"
            }
        },
        "type": "domain",
        "creator": "sim.gretina@example.org",
        "organization": "eswing",
        "links": {
            "self": "/pt/v2/artifact?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57",
            "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67",
            "tag": "/pt/v2/artifact/tag?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57"
        },
        "guid": "838439d8-d291-4e20-dec8-05c8f7f7ba57",
        "user_tags": [
            "malware",
            "scammer"
        ],
        "owner": "eswing",
        "success": {
            "tags": true,
            "monitor": true
        },
        "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
        "monitorable": true,
        "created": "2017-04-15T00:18:06.580000"
    },
    "35012697-41b2-f6ac-9f3f-ed45d6464a65": {
        "global_tags": [
            "registered",
            "phisher",
            "scammer"
        ],
        "system_tags": [
            "registered"
        ],
        "monitor": true,
        "query": "passivetotal.org",
        "tag_meta": {
            "phisher": {
                "creator": "sim.gretina@example.org",
                "created_at": "2017-04-17T20:08:30.929000"
            },
            "scammer": {
                "creator": "sim.gretina@example.org",
                "created_at": "2017-04-17T20:08:30.929000"
            }
        },
        "type": "domain",
        "creator": "sim.gretina@example.org",
        "organization": "eswing",
        "links": {
            "self": "/pt/v2/artifact?artifact=35012697-41b2-f6ac-9f3f-ed45d6464a65",
            "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67",
            "tag": "/pt/v2/artifact/tag?artifact=35012697-41b2-f6ac-9f3f-ed45d6464a65"
        },
        "guid": "35012697-41b2-f6ac-9f3f-ed45d6464a65",
        "user_tags": [
            "phisher",
            "scammer"
        ],
        "owner": "eswing",
        "success": {
            "tags": true,
            "monitor": true
        },
        "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
        "monitorable": true,
        "created": "2017-04-17T19:58:26.765000"
    }
}
			

Create Artifact

Create an artifact.

Curl Example

curl -XPUT -H "Content-Type: application/json" --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/pt/v2/artifact'  --data '{"project": "f083816f-9769-16cb-4660-4b389dc3ae67", "query": "example.org"}'

Parameters

Field Field Type Description
projectUUID the project id the artifact will live on
queryString the actual artifact query (passivetotal.org, 8.8.8.8, etc).
type (optional)String the type of the artifact (domain, ip, etc), or inferred by query string if domain or ip (optional).
tags (optional)String[] the tags the new artifact will have

JSON Request

{
    "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
    "query": "example.org"
}
			

Sample Response

{
    "monitor": false,
    "type": "domain",
    "owner": "riskiq",
    "monitorable": true,
    "global_tags": [
        "registered",
        "foobar"
    ],
    "system_tags": [
        "registered"
    ],
    "creator": "sim.gretina@example.org",
    "guid": "838439d8-d291-4e20-dec8-05c8f7f7ba57",
    "user_tags": [
        "foobar"
    ],
    "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
    "links": {
        "tag": "/pt/v2/artifact/tag?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57",
        "self": "/pt/v2/artifact?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57",
        "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67"
    },
    "created": "2017-04-15T00:18:06.580797",
    "query": "example.org",
    "organization": "riskiq",
    "success": true,
    "tag_meta": {
        "foobar": {
            "creator": "sim.gretina@example.org",
            "created_at": "2017-04-13T01:34:44.592000"
        }
    }
}
			

Delete Artifact

Delete an artifact with a UUID.

Curl Example

curl -XDELETE -H "Content-Type: application/json" --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/pt/v2/artifact' --data '{"artifact": "a9969326-4310-175d-d422-e83a36edaae0"}'

Parameters

Field Field Type Description
artifactUUID the artifact id

JSON Request

{
    "artifact": "a9969326-4310-175d-d422-e83a36edaae0"
}
			

Sample Response

{
    "links": {
        "self": "/pt/v2/artifact?artifact=a9969326-4310-175d-d422-e83a36edaae0",
        "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67",
        "tag": "/pt/v2/artifact/tag?artifact=a9969326-4310-175d-d422-e83a36edaae0"
    },
    "owner": "riskiq",
    "tag_meta": {
        "fizzbuzz": {
            "created_at": "2017-04-15T00:32:04.782000",
            "creator": "sim.gretina@example.org"
        },
        "foobar": {
            "created_at": "2017-04-15T00:32:04.782000",
            "creator": "sim.gretina@example.org"
        }
    },
    "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
    "created": "2017-04-15T00:31:51.033000",
    "global_tags": [
        "registered",
        "fizzbuzz",
        "foobar"
    ],
    "system_tags": [
        "registered"
    ],
    "query": "badguy.example.org",
    "creator": "sim.gretina@example.org",
    "monitor": true,
    "type": "domain",
    "organization": "riskiq",
    "guid": "a9969326-4310-175d-d422-e83a36edaae0",
    "success": true,
    "monitorable": true,
    "user_tags": [
        "fizzbuzz",
        "foobar"
    ]
}
			

Find Artifact

Read existing artifacts. If no filters are passed, this returns all your personal artifacts created by you or your organization.

Curl Example

 # Artifact query 
$ curl --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/pt/v2/artifact?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57'
# Project query
$ curl --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/pt/v2/artifact?project=f083816f-9769-16cb-4660-4b389dc3ae67'

Parameters

Field Field Type Description
UUID (optional)UUID the artifact id
project (optional)UUID filter by project id
owner (optional)String filter by owner (an email or organization id)
creator (optional)String filter by creator
organization (optional)String filter by organization
query (optional)String filter by query (passivetotal.org, etc)
type (optional)String filter by artifact type (domain, ip, etc)

Sample Response (Artifact)

{
    "monitor": true,
    "type": "domain",
    "owner": "riskiq",
    "monitorable": true,
    "global_tags": [
        "registered",
        "fizzbuzz",
        "foobar"
    ],
    "system_tags": [
        "registered"
    ],
    "creator": "sim.gretina@example.org",
    "guid": "838439d8-d291-4e20-dec8-05c8f7f7ba57",
    "user_tags": [
        "fizzbuzz",
        "foobar"
    ],
    "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
    "links": {
        "tag": "/pt/v2/artifact/tag?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57",
        "self": "/pt/v2/artifact?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57",
        "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67"
    },
    "created": "2017-04-15T00:18:06.580000",
    "query": "example.org",
    "organization": "riskiq",
    "success": true,
    "tag_meta": {
        "fizzbuzz": {
            "creator": "sim.gretina@example.org",
            "created_at": "2017-04-15T00:24:06.071000"
        },
        "foobar": {
            "creator": "sim.gretina@example.org",
            "created_at": "2017-04-13T01:34:44.592000"
        }
    }
}
			

Sample Response (Project)

{
    "artifacts": [
        {
            "links": {
                "self": "/pt/v2/artifact?artifact=a9969326-4310-175d-d422-e83a36edaae0",
                "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67",
                "tag": "/pt/v2/artifact/tag?artifact=a9969326-4310-175d-d422-e83a36edaae0"
            },
            "owner": "riskiq",
            "tag_meta": {
                "fizzbuzz": {
                    "created_at": "2017-04-15T00:32:04.782000",
                    "creator": "sim.gretina@example.org"
                },
                "foobar": {
                    "created_at": "2017-04-15T00:32:04.782000",
                    "creator": "sim.gretina@example.org"
                }
            },
            "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
            "created": "2017-04-15T00:31:51.033000",
            "global_tags": [
                "registered",
                "fizzbuzz",
                "foobar"
            ],
            "system_tags": [
                "registered"
            ],
            "creator": "sim.gretina@example.org",
            "monitor": true,
            "type": "domain",
            "organization": "riskiq",
            "guid": "a9969326-4310-175d-d422-e83a36edaae0",
            "monitorable": true,
            "user_tags": [
                "fizzbuzz",
                "foobar"
            ],
            "query": "badguy.example.org"
        },
        {
            "links": {
                "self": "/pt/v2/artifact?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57",
                "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67",
                "tag": "/pt/v2/artifact/tag?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57"
            },
            "owner": "riskiq",
            "tag_meta": {
                "fizzbuzz": {
                    "created_at": "2017-04-15T00:24:06.071000",
                    "creator": "sim.gretina@example.org"
                },
                "foobar": {
                    "created_at": "2017-04-13T01:34:44.592000",
                    "creator": "sim.gretina@example.org"
                }
            },
            "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
            "created": "2017-04-15T00:18:06.580000",
            "global_tags": [
                "registered",
                "fizzbuzz",
                "foobar"
            ],
            "system_tags": [
                "registered"
            ],
            "creator": "sim.gretina@example.org",
            "monitor": true,
            "type": "domain",
            "organization": "riskiq",
            "guid": "838439d8-d291-4e20-dec8-05c8f7f7ba57",
            "monitorable": true,
            "user_tags": [
                "fizzbuzz",
                "foobar"
            ],
            "query": "example.org"
        }
    ],
    "success": true
}
			

Update Artifact

Update artifact, or toggle monitoring status. If you want to change the query or artifact type, simply delete it and create a new one. Use /pt/v2/artifact/tag to add or delete tags without setting everything at once.

Curl Example

$ curl -XPOST -H "Content-Type: application/json" --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/pt/v2/artifact' --data '{"artifact": "838439d8-d291-4e20-dec8-05c8f7f7ba57", "monitor": true, "tags": ["fizzbuzz", "foobar"]}'

Parameters

Field Field Type Description
artifact UUID the artifact id to update
monitor (optional)Boolean whether to monitor the artifact
tags (optional)String[] sets the artifact's tags to this list

JSON Request

{
    "artifact": "838439d8-d291-4e20-dec8-05c8f7f7ba57",
    "monitor": true,
    "tags": [
        "fizzbuzz",
        "foobar"
    ]
}

Sample Response

{
    "monitor": true,
    "type": "domain",
    "owner": "riskiq",
    "monitorable": true,
    "global_tags": [
        "registered",
        "fizzbuzz",
        "foobar"
    ],
    "system_tags": [
        "registered"
    ],
    "creator": "sim.gretina@example.org",
    "guid": "838439d8-d291-4e20-dec8-05c8f7f7ba57",
    "user_tags": [
        "fizzbuzz",
        "foobar"
    ],
    "project": "f083816f-9769-16cb-4660-4b389dc3ae67",
    "links": {
        "tag": "/pt/v2/artifact/tag?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57",
        "self": "/pt/v2/artifact?artifact=838439d8-d291-4e20-dec8-05c8f7f7ba57",
        "project": "/pt/v2/project?project=f083816f-9769-16cb-4660-4b389dc3ae67"
    },
    "created": "2017-04-15T00:18:06.580000",
    "query": "example.org",
    "organization": "riskiq",
    "success": {
        "monitor": true,
        "tags": true
    },
    "tag_meta": {
        "fizzbuzz": {
            "creator": "sim.gretina@example.org",
            "created_at": "2017-04-15T00:24:06.071000"
        },
        "foobar": {
            "creator": "sim.gretina@example.org",
            "created_at": "2017-04-13T01:34:44.592000"
        }
    }
}