Submit a link
curl --request POST \
--url https://public-api.adclear.ai/v1/links \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-External-User-ID: <x-external-user-id>' \
--data '
{
"url": "https://example.com/landing-page",
"figmaFrameId": "123:456"
}
'import requests
url = "https://public-api.adclear.ai/v1/links"
payload = {
"url": "https://example.com/landing-page",
"figmaFrameId": "123:456"
}
headers = {
"X-External-User-ID": "<x-external-user-id>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-External-User-ID': '<x-external-user-id>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({url: 'https://example.com/landing-page', figmaFrameId: '123:456'})
};
fetch('https://public-api.adclear.ai/v1/links', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://public-api.adclear.ai/v1/links",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://example.com/landing-page',
'figmaFrameId' => '123:456'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-External-User-ID: <x-external-user-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://public-api.adclear.ai/v1/links"
payload := strings.NewReader("{\n \"url\": \"https://example.com/landing-page\",\n \"figmaFrameId\": \"123:456\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-External-User-ID", "<x-external-user-id>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://public-api.adclear.ai/v1/links")
.header("X-External-User-ID", "<x-external-user-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://example.com/landing-page\",\n \"figmaFrameId\": \"123:456\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://public-api.adclear.ai/v1/links")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-External-User-ID"] = '<x-external-user-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://example.com/landing-page\",\n \"figmaFrameId\": \"123:456\"\n}"
response = http.request(request)
puts response.read_body{
"uploadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "completed",
"fileFormat": "image",
"source": "screenshot",
"sourceUrl": "<string>",
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"originalFileName": "<string>",
"previewUrl": "<string>"
}{
"uploadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "processing",
"fileFormat": "text",
"source": "screenshot",
"sourceUrl": "<string>",
"statusUrl": "/v1/links/6f1c1c2e-1234-4bcd-9e0f-abcdef012345?source=gdrive",
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"frameId": "<string>",
"frameName": "<string>",
"originalFileName": "<string>",
"sizeBytes": 123,
"previewUrl": "<string>"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}Links
Submit a link
Captures a link as an upload that can be used in promotions. Generic http(s) URLs are captured synchronously as a full-page screenshot — the call can take up to 2 minutes, so set a generous client timeout; returns 201 with an uploadId. Figma links (figma.com) are imported asynchronously via the Figma API — the file must be shared with “anyone with the link”; returns 202 with an uploadId to poll via the returned statusUrl. A frame must be identified via the node-id query parameter in the URL (“copy link to frame” in Figma) or the figmaFrameId field; discover frame IDs via POST /v1/links/figma/frames. Google Drive and Google Docs links (drive.google.com, docs.google.com) are imported asynchronously via the Google Drive API — the file must be shared with “anyone with the link”; returns 202 with an uploadId to poll via the returned statusUrl. Native Docs, Sheets and Slides are converted to PDF, so check the returned fileFormat rather than assuming “image”. Always poll the statusUrl exactly as returned — it carries the source the poll needs. This endpoint is limited to 10 requests per minute per API key.
POST
/
v1
/
links
Submit a link
curl --request POST \
--url https://public-api.adclear.ai/v1/links \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-External-User-ID: <x-external-user-id>' \
--data '
{
"url": "https://example.com/landing-page",
"figmaFrameId": "123:456"
}
'import requests
url = "https://public-api.adclear.ai/v1/links"
payload = {
"url": "https://example.com/landing-page",
"figmaFrameId": "123:456"
}
headers = {
"X-External-User-ID": "<x-external-user-id>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-External-User-ID': '<x-external-user-id>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({url: 'https://example.com/landing-page', figmaFrameId: '123:456'})
};
fetch('https://public-api.adclear.ai/v1/links', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://public-api.adclear.ai/v1/links",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://example.com/landing-page',
'figmaFrameId' => '123:456'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-External-User-ID: <x-external-user-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://public-api.adclear.ai/v1/links"
payload := strings.NewReader("{\n \"url\": \"https://example.com/landing-page\",\n \"figmaFrameId\": \"123:456\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-External-User-ID", "<x-external-user-id>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://public-api.adclear.ai/v1/links")
.header("X-External-User-ID", "<x-external-user-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://example.com/landing-page\",\n \"figmaFrameId\": \"123:456\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://public-api.adclear.ai/v1/links")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-External-User-ID"] = '<x-external-user-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://example.com/landing-page\",\n \"figmaFrameId\": \"123:456\"\n}"
response = http.request(request)
puts response.read_body{
"uploadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "completed",
"fileFormat": "image",
"source": "screenshot",
"sourceUrl": "<string>",
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"originalFileName": "<string>",
"previewUrl": "<string>"
}{
"uploadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "processing",
"fileFormat": "text",
"source": "screenshot",
"sourceUrl": "<string>",
"statusUrl": "/v1/links/6f1c1c2e-1234-4bcd-9e0f-abcdef012345?source=gdrive",
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"frameId": "<string>",
"frameName": "<string>",
"originalFileName": "<string>",
"sizeBytes": 123,
"previewUrl": "<string>"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}Authorizations
API key passed as Bearer token
Headers
Identifier of the acting user in the calling system (e.g. a Workfront user id). Recorded against every audited action this request performs.
Acting user email. Only meaningful on keys with act-on-behalf enabled, where it is resolved to the matching Adclear user and is mandatory on writes. Ignored on ordinary keys.
Body
application/json
The link to capture. Generic http(s) URLs are captured as a full-page screenshot. Figma links (figma.com) are imported as an image via the Figma API — the file must be shared with "anyone with the link", and a frame must be identified via a node-id in the URL ("copy link to frame" in Figma) or the figmaFrameId field. Google Drive and Google Docs links (drive.google.com, docs.google.com) are imported via the Google Drive API — the file must be shared with "anyone with the link", native Docs, Sheets and Slides arrive as PDF, and plain text files are rejected (submit text inline on the promotion instead).
Maximum string length:
2048Example:
"https://example.com/landing-page"
Figma frame (node) ID to import, e.g. "123:456". Only valid for figma.com URLs. When omitted, the node-id query parameter from the URL is used. Discover frame IDs via POST /v1/links/figma/frames.
Minimum string length:
1Example:
"123:456"
Response
URL captured — the upload is ready to use
Upload ID of the captured image. Pass in uploadIds when creating a promotion or version (with fileFormat "image").
Available options:
completed Available options:
image Which upstream captured the link
Available options:
screenshot The submitted URL, echoed back
Correlation ID for request tracing. Include in support requests.
Time-limited signed URL to preview the captured image
Was this page helpful?