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
Getting Started Actions Artifact Articles Data Card Enrichment Services Monitor Project SSL Certificates Tag Artifact Trackers Host Attributes Cookies Components 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"]} ]}'

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"
        }
    ]
}
			

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"]}'

JSON Request

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

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"]} ]}'

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"
            ]
        }
    ]
}
			

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"}'

JSON Request

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

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"}'

JSON Request

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

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'

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"
        }
    }
}
			

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"]}'

JSON Request

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

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"
        }
    }
}