Archive Partners API
Archive API allows you to access enriched details about your community. The Archive Community is representative of the social profiles that are captured and tracked through an Archive Community CDP.
This detailed information ranges from profile information to post engagement metrics. This data has been used for enriching ambassador/loyalty programs, automating marketing flows, and performance measurement.
GraphQL
Archive API is built on GraphQL query language: graphql.org. If you already have an API token, you can try it with our API explorer.
API Endpoints
POST: https://app.archive.com/api/v1
Headers
# Get token from our team
Authorization: Bearer <YOUR_TOKEN_HERE>
# If you have multiple shops you need to pass Shop ID in header
SHOP-ID: 123
Authentication
All queries require a valid access token. In order to get your access token, contact api@archive.com. Include your token as an Authorization header on all queries.
Webhooks
You can receive webhooks for specific events. List of available events: WebhookSubscriptionsEventsEnum
To start receiving webhooks, you need to subscribe to an event with webhookSubscriptionCreate mutation. Once subscribed, Archive will send MediaItem object with attributes in underscore style to callback_url every time there is an event trigger.
Queries
creator
Description
Returns a Creator resource by ID.
Response
Returns a Creator
Arguments
Name | Description |
---|---|
id -
Int
|
|
accountName -
String
|
|
provider -
IntegrationProviderEnum
|
|
fallback -
Boolean
|
Example
Query
query creator(
$id: Int,
$accountName: String,
$provider: IntegrationProviderEnum,
$fallback: Boolean
) {
creator(
id: $id,
accountName: $accountName,
provider: $provider,
fallback: $fallback
) {
accountName
authorized
avatarUrl
biography
followersCount
followingCount
id
provider
verified
}
}
Variables
{
"id": 987,
"accountName": "xyz789",
"provider": "INSTAGRAM",
"fallback": true
}
Response
{
"data": {
"creator": {
"accountName": "abc123",
"authorized": false,
"avatarUrl": "xyz789",
"biography": "xyz789",
"followersCount": 987,
"followingCount": 987,
"id": 987,
"provider": "INSTAGRAM",
"verified": true
}
}
}
creatorAudienceReport
Description
Returns a Creator audience report.
Response
Returns an AudienceReportResponse!
Arguments
Name | Description |
---|---|
id -
Int
|
|
accountName -
String
|
|
provider -
IntegrationProviderEnum
|
Example
Query
query creatorAudienceReport(
$id: Int,
$accountName: String,
$provider: IntegrationProviderEnum
) {
creatorAudienceReport(
id: $id,
accountName: $accountName,
provider: $provider
) {
accountName
audienceReport
id
provider
}
}
Variables
{
"id": 987,
"accountName": "abc123",
"provider": "INSTAGRAM"
}
Response
{
"data": {
"creatorAudienceReport": {
"accountName": "xyz789",
"audienceReport": {},
"id": 123,
"provider": "INSTAGRAM"
}
}
}
creatorPosts
Description
Returns a Creator posts.
Response
Returns a MediaItemConnection!
Arguments
Name | Description |
---|---|
id -
Int
|
|
accountName -
String
|
|
provider -
IntegrationProviderEnum
|
|
after -
String
|
Returns the elements in the list that come after the specified cursor. |
before -
String
|
Returns the elements in the list that come before the specified cursor. |
first -
Int
|
Returns the first n elements from the list. |
last -
Int
|
Returns the last n elements from the list. |
Example
Query
query creatorPosts(
$id: Int,
$accountName: String,
$provider: IntegrationProviderEnum,
$after: String,
$before: String,
$first: Int,
$last: Int
) {
creatorPosts(
id: $id,
accountName: $accountName,
provider: $provider,
after: $after,
before: $before,
first: $first,
last: $last
) {
edges {
cursor
node {
caption
contents {
contentUrl
displayUrl
height
id
type
width
}
creator {
accountName
authorized
avatarUrl
biography
followersCount
followingCount
id
provider
verified
}
engagement {
at
commentCount
likeCount
playCount
viewCount
}
engagementHistory {
at
commentCount
likeCount
playCount
viewCount
}
externalId
hashtags
id
location {
address
city
lat
lng
name
}
mentions
provider
takenAt
type
usageRightsStatus
}
}
nodes {
caption
contents {
contentUrl
displayUrl
height
id
type
width
}
creator {
accountName
authorized
avatarUrl
biography
followersCount
followingCount
id
provider
verified
}
engagement {
at
commentCount
likeCount
playCount
viewCount
}
engagementHistory {
at
commentCount
likeCount
playCount
viewCount
}
externalId
hashtags
id
location {
address
city
lat
lng
name
}
mentions
provider
takenAt
type
usageRightsStatus
}
pageInfo {
endCursor
hasNextPage
hasPreviousPage
startCursor
}
totalCount
}
}
Variables
{
"id": 123,
"accountName": "xyz789",
"provider": "INSTAGRAM",
"after": "abc123",
"before": "abc123",
"first": 987,
"last": 987
}
Response
{
"data": {
"creatorPosts": {
"edges": [MediaItemEdge],
"nodes": [MediaItem],
"pageInfo": PageInfo,
"totalCount": 987
}
}
}
mediaItem
Description
Returns a MediaItem resource by ID or externalID.
Example
Query
query mediaItem(
$id: String,
$externalId: String
) {
mediaItem(
id: $id,
externalId: $externalId
) {
caption
contents {
contentUrl
displayUrl
height
id
type
width
}
creator {
accountName
authorized
avatarUrl
biography
followersCount
followingCount
id
provider
verified
}
engagement {
at
commentCount
likeCount
playCount
viewCount
}
engagementHistory {
at
commentCount
likeCount
playCount
viewCount
}
externalId
hashtags
id
location {
address
city
lat
lng
name
}
mentions
provider
takenAt
type
usageRightsStatus
}
}
Variables
{
"id": "abc123",
"externalId": "abc123"
}
Response
{
"data": {
"mediaItem": {
"caption": "xyz789",
"contents": [MediaContent],
"creator": Creator,
"engagement": [MediaItemsEngagement],
"engagementHistory": [MediaItemsEngagement],
"externalId": "xyz789",
"hashtags": ["xyz789"],
"id": 4,
"location": MediaItemLocation,
"mentions": ["xyz789"],
"provider": "INSTAGRAM",
"takenAt": ISO8601DateTime,
"type": "POST",
"usageRightsStatus": "REQUESTED"
}
}
}
mediaItems
Description
Gets portion of media items.
Response
Returns a MediaItemConnection!
Arguments
Name | Description |
---|---|
filter -
Filter
|
|
after -
String
|
Returns the elements in the list that come after the specified cursor. |
before -
String
|
Returns the elements in the list that come before the specified cursor. |
first -
Int
|
Returns the first n elements from the list. |
last -
Int
|
Returns the last n elements from the list. |
Example
Query
query mediaItems(
$filter: Filter,
$after: String,
$before: String,
$first: Int,
$last: Int
) {
mediaItems(
filter: $filter,
after: $after,
before: $before,
first: $first,
last: $last
) {
edges {
cursor
node {
caption
contents {
contentUrl
displayUrl
height
id
type
width
}
creator {
accountName
authorized
avatarUrl
biography
followersCount
followingCount
id
provider
verified
}
engagement {
at
commentCount
likeCount
playCount
viewCount
}
engagementHistory {
at
commentCount
likeCount
playCount
viewCount
}
externalId
hashtags
id
location {
address
city
lat
lng
name
}
mentions
provider
takenAt
type
usageRightsStatus
}
}
nodes {
caption
contents {
contentUrl
displayUrl
height
id
type
width
}
creator {
accountName
authorized
avatarUrl
biography
followersCount
followingCount
id
provider
verified
}
engagement {
at
commentCount
likeCount
playCount
viewCount
}
engagementHistory {
at
commentCount
likeCount
playCount
viewCount
}
externalId
hashtags
id
location {
address
city
lat
lng
name
}
mentions
provider
takenAt
type
usageRightsStatus
}
pageInfo {
endCursor
hasNextPage
hasPreviousPage
startCursor
}
totalCount
}
}
Variables
{
"filter": Filter,
"after": "xyz789",
"before": "xyz789",
"first": 987,
"last": 987
}
Response
{
"data": {
"mediaItems": {
"edges": [MediaItemEdge],
"nodes": [MediaItem],
"pageInfo": PageInfo,
"totalCount": 123
}
}
}
webhookSubscriptions
Description
Gets list of webhook subscriptions by event.
Response
Returns [WebhookSubscription!]
Arguments
Name | Description |
---|---|
event -
WebhookSubscriptionsEventsEnum
|
Example
Query
query webhookSubscriptions($event: WebhookSubscriptionsEventsEnum) {
webhookSubscriptions(event: $event) {
callbackUrl
event
id
version
}
}
Variables
{"event": "MEDIA_ITEM_CREATED"}
Response
{
"data": {
"webhookSubscriptions": [
{
"callbackUrl": "abc123",
"event": "MEDIA_ITEM_CREATED",
"id": 4,
"version": "v0"
}
]
}
}
Mutations
creatorAddTag
Description
Add custom tag to influencer.
Example
Query
mutation creatorAddTag(
$id: ID!,
$name: String!
) {
creatorAddTag(
id: $id,
name: $name
) {
id
name
shopId
type
}
}
Variables
{
"id": "4",
"name": "xyz789"
}
Response
{
"data": {
"creatorAddTag": {
"id": 4,
"name": "abc123",
"shopId": 4,
"type": "abc123"
}
}
}
creatorTrackingStart
Description
Start track media items from Creator.
Example
Query
mutation creatorTrackingStart($id: Int!) {
creatorTrackingStart(id: $id) {
accountName
authorized
avatarUrl
biography
followersCount
followingCount
id
provider
verified
}
}
Variables
{"id": 987}
Response
{
"data": {
"creatorTrackingStart": {
"accountName": "abc123",
"authorized": true,
"avatarUrl": "xyz789",
"biography": "abc123",
"followersCount": 987,
"followingCount": 123,
"id": 987,
"provider": "INSTAGRAM",
"verified": false
}
}
}
creatorTrackingStop
Description
Stop track media items from Creator.
Example
Query
mutation creatorTrackingStop($id: Int!) {
creatorTrackingStop(id: $id) {
accountName
authorized
avatarUrl
biography
followersCount
followingCount
id
provider
verified
}
}
Variables
{"id": 987}
Response
{
"data": {
"creatorTrackingStop": {
"accountName": "abc123",
"authorized": false,
"avatarUrl": "abc123",
"biography": "xyz789",
"followersCount": 123,
"followingCount": 987,
"id": 987,
"provider": "INSTAGRAM",
"verified": false
}
}
}
mediaItemAddTag
Description
Add custom tag to media item.
Example
Query
mutation mediaItemAddTag(
$id: ID!,
$name: String!
) {
mediaItemAddTag(
id: $id,
name: $name
) {
id
name
shopId
type
}
}
Variables
{
"id": "4",
"name": "xyz789"
}
Response
{
"data": {
"mediaItemAddTag": {
"id": 4,
"name": "xyz789",
"shopId": 4,
"type": "abc123"
}
}
}
mediaItemAddToCollection
Description
Add media item to collection.
Response
Returns a Boolean
Example
Query
mutation mediaItemAddToCollection(
$id: ID!,
$collectionId: ID,
$collectionName: String
) {
mediaItemAddToCollection(
id: $id,
collectionId: $collectionId,
collectionName: $collectionName
)
}
Variables
{
"id": 4,
"collectionId": "4",
"collectionName": "xyz789"
}
Response
{"data": {"mediaItemAddToCollection": false}}
webhookSubscriptionCreate
Description
Creates a new webhook subscription.
Response
Returns a WebhookSubscription
Arguments
Name | Description |
---|---|
version -
WebhookSubscriptionsVersionsEnum!
|
|
event -
WebhookSubscriptionsEventsEnum!
|
|
callbackUrl -
String!
|
Example
Query
mutation webhookSubscriptionCreate(
$version: WebhookSubscriptionsVersionsEnum!,
$event: WebhookSubscriptionsEventsEnum!,
$callbackUrl: String!
) {
webhookSubscriptionCreate(
version: $version,
event: $event,
callbackUrl: $callbackUrl
) {
callbackUrl
event
id
version
}
}
Variables
{
"version": "v0",
"event": "MEDIA_ITEM_CREATED",
"callbackUrl": "xyz789"
}
Response
{
"data": {
"webhookSubscriptionCreate": {
"callbackUrl": "abc123",
"event": "MEDIA_ITEM_CREATED",
"id": "4",
"version": "v0"
}
}
}
webhookSubscriptionDelete
Description
Deletes a webhook subscription.
Response
Returns a Boolean
Arguments
Name | Description |
---|---|
event -
WebhookSubscriptionsEventsEnum!
|
Example
Query
mutation webhookSubscriptionDelete($event: WebhookSubscriptionsEventsEnum!) {
webhookSubscriptionDelete(event: $event)
}
Variables
{"event": "MEDIA_ITEM_CREATED"}
Response
{"data": {"webhookSubscriptionDelete": false}}
Types
AudienceReportResponse
Fields
Field Name | Description |
---|---|
accountName -
String!
|
Name of creator account on Instagram or TikTok. |
audienceReport -
JSON!
|
Audience report. |
id -
Int!
|
Creator's unique identifier in Archive's system. |
provider -
IntegrationProviderEnum!
|
Platform where creator exists. INSTAGRAM or TIKTOK. |
Example
{
"accountName": "xyz789",
"audienceReport": {},
"id": 987,
"provider": "INSTAGRAM"
}
Boolean
Description
Represents true
or false
values.
Example
true
Creator
Fields
Field Name | Description |
---|---|
accountName -
String!
|
Name of creator account on Instagram or TikTok. |
authorized -
Boolean!
|
Whether the creator has been authorized. |
avatarUrl -
String
|
URL of the creator's profile picture. |
biography -
String
|
Creator's bio (if available). |
followersCount -
Int
|
Number of creator's followers. |
followingCount -
Int
|
Number of accounts creator is following. |
id -
Int!
|
Unique identifier in Archive's system. |
provider -
IntegrationProviderEnum!
|
Platform where creator exists. INSTAGRAM or TIKTOK. |
verified -
Boolean
|
Whether the creator is verified by the platform. |
Example
{
"accountName": "abc123",
"authorized": false,
"avatarUrl": "abc123",
"biography": "abc123",
"followersCount": 987,
"followingCount": 123,
"id": 987,
"provider": "INSTAGRAM",
"verified": true
}
Filter
Fields
Input Field | Description |
---|---|
itemProviders -
[IntegrationProviderEnum!]
|
Types of the items |
itemTypes -
[TypesEnum!]
|
Types of the items |
creatorAccountName -
[String!]
|
Creator Account Names. Default = [] |
creatorVerified -
[Boolean!]
|
Only verified influencers |
usageRightsStatus -
[StatusesEnum!]
|
Usage Rights request status |
Example
{
"itemProviders": ["INSTAGRAM"],
"itemTypes": ["POST"],
"creatorAccountName": ["abc123"],
"creatorVerified": [false],
"usageRightsStatus": ["REQUESTED"]
}
ID
Description
Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or
as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended
to be human-readable. When expected as an input type, any string (such as
"VXNlci0xMA=="
) or integer (such as 4
) input value will be
accepted as an ID.
Example
4
ISO8601DateTime
Description
An ISO 8601-encoded datetime
Example
ISO8601DateTime
Int
Description
Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
Example
987
IntegrationProviderEnum
Values
Enum Value | Description |
---|---|
|
|
|
Example
"INSTAGRAM"
JSON
Description
Represents untyped JSON
Example
{}
MediaContent
Fields
Field Name | Description |
---|---|
contentUrl -
String
|
URL of image or video file. |
displayUrl -
String
|
URL of video thumbnail. Will be the same as content_url for images. |
height -
Int
|
Height of media file in px. |
id -
Int!
|
Unique identifier in Archive's system. |
type -
String!
|
Type of media file. IMAGE or VIDEO. |
width -
Int
|
Width of media file in px. |
Example
{
"contentUrl": "xyz789",
"displayUrl": "abc123",
"height": 987,
"id": 123,
"type": "xyz789",
"width": 987
}
MediaItem
Fields
Field Name | Description |
---|---|
caption -
String
|
Content caption. |
contents -
[MediaContent!]!
|
Files which represent the content of an item. For carousels, there will be multiple. |
creator -
Creator!
|
Information about the content creator. |
engagement -
[MediaItemsEngagement!]
|
We can track posts for X days and gather post engagement dynamics. |
engagementHistory -
[MediaItemsEngagement!]
|
We can track posts for X days and gather post engagement dynamics. |
externalId -
String!
|
The ID of an item on Instagram or TikTok. |
hashtags -
[String!]
|
Hashtags that are used in the content. |
id -
ID!
|
Unique identifier in Archive's system. |
location -
MediaItemLocation
|
Content location description. |
mentions -
[String!]
|
Mentions that are used in the content. |
provider -
IntegrationProviderEnum!
|
Platform where content exists. INSTAGRAM or TIKTOK. |
takenAt -
ISO8601DateTime!
|
Timestamp of when content was uploaded to social media (UTC). |
type -
TypesEnum!
|
Type of archived content. POST, REEL, STORY or TIKTOK. |
usageRightsStatus -
StatusesEnum
|
Status of usage rights request for content. REQUESTED, APPROVED or REJECTED. |
Example
{
"caption": "xyz789",
"contents": [MediaContent],
"creator": Creator,
"engagement": [MediaItemsEngagement],
"engagementHistory": [MediaItemsEngagement],
"externalId": "abc123",
"hashtags": ["xyz789"],
"id": "4",
"location": MediaItemLocation,
"mentions": ["abc123"],
"provider": "INSTAGRAM",
"takenAt": ISO8601DateTime,
"type": "POST",
"usageRightsStatus": "REQUESTED"
}
MediaItemConnection
Description
The connection type for MediaItem.
Fields
Field Name | Description |
---|---|
edges -
[MediaItemEdge]
|
A list of edges. |
nodes -
[MediaItem]
|
A list of nodes. |
pageInfo -
PageInfo!
|
Information to aid in pagination. |
totalCount -
Int!
|
Example
{
"edges": [MediaItemEdge],
"nodes": [MediaItem],
"pageInfo": PageInfo,
"totalCount": 123
}
MediaItemEdge
MediaItemLocation
MediaItemsEngagement
Fields
Field Name | Description |
---|---|
at -
ISO8601DateTime!
|
Timestamp of when engagement metrics were captured. |
commentCount -
Int
|
Number of comments. |
likeCount -
Int
|
Number of likes. |
playCount -
Int
|
Number of plays (if available). |
viewCount -
Int
|
Number of views (if available). |
Example
{
"at": ISO8601DateTime,
"commentCount": 987,
"likeCount": 123,
"playCount": 987,
"viewCount": 987
}
PageInfo
Description
Information about pagination in a connection.
Fields
Field Name | Description |
---|---|
endCursor -
String
|
When paginating forwards, the cursor to continue. |
hasNextPage -
Boolean!
|
When paginating forwards, are there more items? |
hasPreviousPage -
Boolean!
|
When paginating backwards, are there more items? |
startCursor -
String
|
When paginating backwards, the cursor to continue. |
Example
{
"endCursor": "abc123",
"hasNextPage": false,
"hasPreviousPage": false,
"startCursor": "abc123"
}
ShopLabel
StatusesEnum
Values
Enum Value | Description |
---|---|
|
|
|
|
|
Example
"REQUESTED"
String
Description
Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.
Example
"abc123"
TypesEnum
Values
Enum Value | Description |
---|---|
|
|
|
|
|
Example
"POST"
WebhookSubscription
Fields
Field Name | Description |
---|---|
callbackUrl -
String!
|
URL of where we will send webhook payload. |
event -
WebhookSubscriptionsEventsEnum!
|
Event which triggers webhook. |
id -
ID!
|
Unique identifier in Archive's system. |
version -
WebhookSubscriptionsVersionsEnum!
|
Which version of payloads are used. |
Example
{
"callbackUrl": "abc123",
"event": "MEDIA_ITEM_CREATED",
"id": 4,
"version": "v0"
}
WebhookSubscriptionsEventsEnum
Values
Enum Value | Description |
---|---|
|
Triggers when media item comes to Archive. |
|
Triggers when we add a record into media item engagement history. |
Example
"MEDIA_ITEM_CREATED"
WebhookSubscriptionsVersionsEnum
Values
Enum Value | Description |
---|---|
|
|
|
Example
"v0"