Jump to examples ↓

Query

itemIdsByUrl

Look up item IDs by social media URL within the current workspace. Accepts any public HTTP(S) URL. INVALID_URL means a malformed or non-HTTP URL, or a private/reserved host. A valid public URL that does not resolve returns NOT_FOUND: an unrecognized shape, a short link, or no matching item. Recognized shapes (not exhaustive): Instagram (/p/, /reel/, /reels/), TikTok (@user/video/{id}, @user/photo/{id}), and YouTube (/shorts/, /watch?v=, youtu.be/).

MCP: getItemIdsByUrl

Arguments

urls [String!]! required: Public HTTP(S) URLs to look up (1-100). Any public URL is accepted; INVALID_URL only for malformed / non-HTTP URLs or private/reserved hosts, otherwise FOUND or NOT_FOUND.

Returns

Returns [UrlLookupResult!]!.

Object, input and enum types open in place — use + to reveal their fields. A type that is already open above the row stops at a ↻ circular marker, and anything nested past the depth limit links out to its own page instead.

itemId ID: The matching Item UUID, or null if no match was found.
status UrlLookupStatus!: Outcome of the lookup: FOUND, NOT_FOUND, or INVALID_URL.
FOUND: Item found in the current workspace matching the provided public HTTP(S) URL.
INVALID_URL: The input was malformed, used a non-HTTP(S) scheme, or targeted a private/reserved host.
NOT_FOUND: The input was a valid public HTTP(S) URL, but no matching item exists in the current workspace.
url String!: The original input string that was looked up.

Open in explorer ↗

Values are sampled from a demo workspace — substitute your own token and workspace id.

Resolve social media URLs to workspace item IDs.

query.graphql

query ItemIdsByUrlDefault($urls: [String!]!) {
  itemIdsByUrl(urls: $urls) {
    url
    itemId
    status
  }
}

variables.json

{
  "urls": [
    "https://www.instagram.com/p/docs-item-0/"
  ]
}

Headers

Authorization: Bearer docs_demo_token_0000000000000000000000
WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a

Request · cURL

curl https://app.archive.com/api/v2 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer docs_demo_token_0000000000000000000000' \
  -H 'WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a' \
  -d '{
  "query": "query ItemIdsByUrlDefault($urls: [String!]!) {\n  itemIdsByUrl(urls: $urls) {\n    url\n    itemId\n    status\n  }\n}",
  "variables": {
    "urls": [
      "https://www.instagram.com/p/docs-item-0/"
    ]
  }
}'

Request · Node.js

const response = await fetch("https://app.archive.com/api/v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer docs_demo_token_0000000000000000000000",
    "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
  },
  body: JSON.stringify({
    query: `query ItemIdsByUrlDefault($urls: [String!]!) {
  itemIdsByUrl(urls: $urls) {
    url
    itemId
    status
  }
}`,
    variables: {
      "urls": [
        "https://www.instagram.com/p/docs-item-0/"
      ]
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  query ItemIdsByUrlDefault($urls: [String!]!) {
    itemIdsByUrl(urls: $urls) {
      url
      itemId
      status
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "urls" => ["https://www.instagram.com/p/docs-item-0/"] } }.to_json,
  "Content-Type" => "application/json",
  "Authorization" => "Bearer docs_demo_token_0000000000000000000000",
  "WORKSPACE-ID" => "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
)
puts response.body

Request · Python

import json
import requests

query = """
query ItemIdsByUrlDefault($urls: [String!]!) {
  itemIdsByUrl(urls: $urls) {
    url
    itemId
    status
  }
}
"""

response = requests.post(
    "https://app.archive.com/api/v2",
    json={"query": query, "variables": {"urls": ["https://www.instagram.com/p/docs-item-0/"]}},
    headers={
        "Authorization": "Bearer docs_demo_token_0000000000000000000000",
        "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
    },
)
print(json.dumps(response.json(), indent=2))

200 OK 11 lines

{
  "data": {
    "itemIdsByUrl": [
      {
        "url": "https://www.instagram.com/p/docs-item-0/",
        "itemId": "63c311c4-32f0-5d8c-ac02-78b160f2290a",
        "status": "FOUND"
      }
    ]
  }
}