PicSee logo
API docs by Redocly

PicSee Short Link API Document

Download OpenAPI specification:

E-mail: service@picsee.vip URL: https://picsee.io Terms of Service

This is the API documentation for the PicSee URL Shortener.
PicSee offers Free, Basic, and Advanced Plans. For detailed information and documentation updates, please refer to the PicSee API official website: https://picsee.io/developers.

  • If you encounter issues while integrating, please use Postman to take screenshots, and provide your PicSee ID to PicSee customer support. Please DO NOT share your code directly.
  • The API endpoint varies when upgrading to the "Dedicated Host (獨立主機)" or "Fixed IP Server (固定 IP)" plans. Don't hesitate to get in touch with PicSee for more details.
API Plans & Pricing
(Free 800 requests / year)
View Plan

My Account

Account-level endpoints — API plan & usage, domains, tags, tracking tools.

Get API Plans and Usage

One call per second is allowed. If this limit is exceeded, a status code 429 will be returned. A try-catch structure is recommended to retry.
Authorizations:
access_tokenX-API-KeyBearerAuth

Responses

Request samples 

curl -X 'GET' \
'https://api.pics.ee/v2/my/api/status?access_token=YOUR_ACCESS_TOKEN' \
-H 'accept: application/json'

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get API Usage by externalId

Returns the number of short links the caller has created via the API within the specified time range, broken down by `externalId`. Links created without an `externalId` are reported under `externalId: null`.

One call per second is allowed. If exceeded, a status code 429 will be returned. A try-catch structure is recommended to retry.

The default time range is the last 30 days. A custom range may be specified with startTime / endTime, but the range must not exceed 31 days. Results are cached for 1 hour.

Authorizations:
access_tokenX-API-KeyBearerAuth
query Parameters
startTime
string
Example: startTime=2026-04-20T00:00:00

Start time of the query range (Taipei time, format YYYY-MM-DDTHH:mm:ss). Defaults to 30 days before endTime.

endTime
string
Example: endTime=2026-05-20T00:00:00

End time of the query range (Taipei time, format YYYY-MM-DDTHH:mm:ss). Defaults to the current time, floored to the current hour. The range between startTime and endTime must not exceed 31 days.

Responses

Request samples 

curl -X 'GET' \
'https://api.pics.ee/v4/my/api/usage?access_token=YOUR_ACCESS_TOKEN' \
-H 'accept: application/json'

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get Available Domains

Returns the brand domains (BSDs), subdomains, and shared root domain available to the caller. Each entry indicates whether HTTPS is enabled and whether it is the account default. Useful for building a domain picker (e.g. the Chrome Extension) instead of asking the user to type a domain manually.

One call per second is allowed. If exceeded, a status code 429 will be returned. A try-catch structure is recommended to retry.

Results are cached for 1 hour.

Authorizations:
access_tokenX-API-KeyBearerAuth

Responses

Request samples 

curl -X 'GET' \
'https://api.pics.ee/v4/my/api/domains?access_token=YOUR_ACCESS_TOKEN' \
-H 'accept: application/json'

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get Available Tags

Returns the tags available to the caller (tag id + value), as previously created on this account. The returned tag IDs can be referenced in other endpoints; the values match the values accepted by `tags` in the create / edit link APIs.

One call per second is allowed. If exceeded, a status code 429 will be returned. A try-catch structure is recommended to retry.

Results are cached for 1 hour.

Authorizations:
access_tokenX-API-KeyBearerAuth

Responses

Request samples 

curl -X 'GET' \
'https://api.pics.ee/v4/my/api/tags?access_token=YOUR_ACCESS_TOKEN' \
-H 'accept: application/json'

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get Available Tracking Tools

Returns the tracking tools remembered on the account: UTM source / medium values previously used, plus saved Meta Pixels and Google Tag (GTM) configurations. Use this to populate dropdowns in tools that create PicSee links, so users can pick from prior values instead of retyping.

One call per second is allowed. If exceeded, a status code 429 will be returned. A try-catch structure is recommended to retry.

Results are cached for 1 hour.

Authorizations:
access_tokenX-API-KeyBearerAuth

Responses

Request samples 

curl -X 'GET' \
'https://api.pics.ee/v4/my/api/trackingTools?access_token=YOUR_ACCESS_TOKEN' \
-H 'accept: application/json'

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

List of Short Links

One call per second is allowed. If this limit is exceeded, a status code 429 will be returned. A try-catch structure is recommended to retry.
Authorizations:
access_tokenX-API-KeyBearerAuth
query Parameters
limit
number
Example: limit=20

Short links displayed per list, defaulting to 20, with an optional maximum of 50.

startTime
string
Example: startTime=2023-11-20T13:00:00

Set the start time for listing short links, queried in descending order from the specified time backward, defaulting to the current time.

prevMapId
number
Example: prevMapId=22198535

Retrieve the list of short links older than this mapId. When both startTime and prevMapId are specified, they will be queried using an AND condition.

isAPI
boolean
Example: isAPI=true

Query only API-generated short links: true for yes, false for no (only non-API-generated links). The default is true.

isStar
boolean
Example: isStar=false

Query only starred short links: true for yes, false for no (only non-starred links). The default is false.

externalId
string
Example: externalId=20231111_campaign

Query short links containing a specific externalId.

Request Body schema: application/json
optional

Search Parameters (Advanced Plan)

When multiple search parameters are provided, higher priority parameters take precedence and lower priority ones are ignored. Priority order (highest to lowest): encodeId > authorId > tag > keyword.

encodeId
string

Search for short links using the slug (requires an exact match to find results). Priority 1 — when provided, all other search parameters are ignored.

authorId
integer

Search for short links created by a specific link author ID. Priority 2 — ignored if encodeId is provided.

tag
string

Search for short links with the specified tag (limit: 3-30 characters). Priority 3 — ignored if encodeId or authorId is provided.

keyword
string

Search for short links with the keyword (limit: 3-30 characters). Priority 4 — ignored if any higher priority parameter (encodeId, authorId, or tag) is provided.

Responses

Request samples

Content type
application/json
{
  • "encodeId": "5b93x9",
  • "authorId": 739,
  • "tag": "facebook_campaign",
  • "keyword": "picsee"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Analytics

Click analytics — overview, daily clicks, platform, referrer, country, and audience labels.

Get Short Link Analytics

There is no call frequency limit; however, the content update frequency may vary depending on the plan.
Authorizations:
access_tokenX-API-KeyBearerAuth
path Parameters
encodeId
required
string
Example: 5b93x9

The slug of the short link

query Parameters
format
string
Enum: "json" "csv"
Example: format=csv

Supported return formats include "json" and "csv". If left blank, the default is "json".

Responses

Request samples 

curl -X 'GET' \
'https://api.pics.ee/v1/links/5b93x9/overview?access_token=YOUR_ACCESS_TOKEN' \
-H 'accept: application/json'

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get Daily Clicks

Returns total clicks and unique clicks aggregated by day within the specified time range.

10 calls per second are allowed for Advanced plan users; 1 call per second for other plans. If exceeded, a status code 429 will be returned. A try-catch structure is recommended to retry.

The default time range is the last 30 days. The maximum lookback is 365 days for Advanced plan users and 30 days for other plans. Results are cached for 10 minutes (Advanced) or 1 hour (other plans).

Authorizations:
access_tokenX-API-KeyBearerAuth
path Parameters
encodeId
required
string
Example: 5b93x9

The slug of the short link

query Parameters
startTime
string
Example: startTime=2026-04-20T00:00:00

Start time of the query range (Taipei time, format YYYY-MM-DDTHH:mm:ss). Defaults to 30 days before endTime.

endTime
string
Example: endTime=2026-05-20T00:00:00

End time of the query range (Taipei time, format YYYY-MM-DDTHH:mm:ss). Defaults to the current time, floored to the cache bucket (10-minute bucket for Advanced, hour bucket for other plans).

format
string
Enum: "json" "csv"
Example: format=csv

Supported return formats include "json" and "csv". If left blank, the default is "json". When csv is specified, the response returns a CSV file with columns: date, totalClicks, uniqueClicks.

Responses

Request samples 

curl -X 'GET' \
'https://api.pics.ee/v4/links/5b93x9/details/dailyClicks?access_token=YOUR_ACCESS_TOKEN' \
-H 'accept: application/json'

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get Click Distribution by Device

Returns unique click counts broken down by device (e.g. `iphone`, `ipad`, `android`, `windows`, `macintosh`, ...) within the specified time range. Devices are returned individually without being grouped into "mobile" / "desktop" buckets — callers can aggregate as needed.

10 calls per second are allowed for Advanced plan users; 1 call per second for other plans. If exceeded, a status code 429 will be returned. A try-catch structure is recommended to retry.

The default time range is the last 30 days. The maximum lookback is 365 days for Advanced plan users and 30 days for other plans. Results are cached for 10 minutes (Advanced) or 1 hour (other plans).

Authorizations:
access_tokenX-API-KeyBearerAuth
path Parameters
encodeId
required
string
Example: 5b93x9

The slug of the short link

query Parameters
startTime
string
Example: startTime=2026-04-20T00:00:00

Start time of the query range (Taipei time, format YYYY-MM-DDTHH:mm:ss). Defaults to 30 days before endTime.

endTime
string
Example: endTime=2026-05-20T00:00:00

End time of the query range (Taipei time, format YYYY-MM-DDTHH:mm:ss). Defaults to the current time, floored to the cache bucket.

format
string
Enum: "json" "csv"
Example: format=csv

Supported return formats include "json" and "csv". If left blank, the default is "json". When csv is specified, the response returns a CSV file with columns: platform, count.

Responses

Request samples 

curl -X 'GET' \
'https://api.pics.ee/v4/links/5b93x9/details/platform?access_token=YOUR_ACCESS_TOKEN' \
-H 'accept: application/json'

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get Click Distribution by Referrer

Returns unique click counts broken down by traffic source (e.g. specific AI Agents, search engines, social platforms, long-tail referrers) within the specified time range. Referrers are returned individually without being collapsed into "AI Agent" or "Others" buckets. Clicks without a referrer are reported as `direct`.

10 calls per second are allowed for Advanced plan users; 1 call per second for other plans. If exceeded, a status code 429 will be returned. A try-catch structure is recommended to retry.

The default time range is the last 30 days. The maximum lookback is 365 days for Advanced plan users and 30 days for other plans. Results are cached for 10 minutes (Advanced) or 1 hour (other plans).

Authorizations:
access_tokenX-API-KeyBearerAuth
path Parameters
encodeId
required
string
Example: 5b93x9

The slug of the short link

query Parameters
startTime
string
Example: startTime=2026-04-20T00:00:00

Start time of the query range (Taipei time, format YYYY-MM-DDTHH:mm:ss). Defaults to 30 days before endTime.

endTime
string
Example: endTime=2026-05-20T00:00:00

End time of the query range (Taipei time, format YYYY-MM-DDTHH:mm:ss). Defaults to the current time, floored to the cache bucket.

format
string
Enum: "json" "csv"
Example: format=csv

Supported return formats include "json" and "csv". If left blank, the default is "json". When csv is specified, the response returns a CSV file with columns: referer, count.

Responses

Request samples 

curl -X 'GET' \
'https://api.pics.ee/v4/links/5b93x9/details/referrers?access_token=YOUR_ACCESS_TOKEN' \
-H 'accept: application/json'

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get Click Distribution by Country

Returns unique click counts broken down by country within the specified time range. Results are aggregated at country granularity only — no city-level breakdown. Clicks from unknown countries are bucketed as `Others`.

10 calls per second are allowed for Advanced plan users; 1 call per second for other plans. If exceeded, a status code 429 will be returned. A try-catch structure is recommended to retry.

The default time range is the last 30 days. The maximum lookback is 365 days for Advanced plan users and 30 days for other plans. Results are cached for 10 minutes (Advanced) or 1 hour (other plans).

Authorizations:
access_tokenX-API-KeyBearerAuth
path Parameters
encodeId
required
string
Example: 5b93x9

The slug of the short link

query Parameters
startTime
string
Example: startTime=2026-04-20T00:00:00

Start time of the query range (Taipei time, format YYYY-MM-DDTHH:mm:ss). Defaults to 30 days before endTime.

endTime
string
Example: endTime=2026-05-20T00:00:00

End time of the query range (Taipei time, format YYYY-MM-DDTHH:mm:ss). Defaults to the current time, floored to the cache bucket.

format
string
Enum: "json" "csv"
Example: format=csv

Supported return formats include "json" and "csv". If left blank, the default is "json". When csv is specified, the response returns a CSV file with columns: name, code, count.

Responses

Request samples 

curl -X 'GET' \
'https://api.pics.ee/v4/links/5b93x9/details/regions?access_token=YOUR_ACCESS_TOKEN' \
-H 'accept: application/json'

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get Audience Labels

Returns the audience labels of a short link, split into two groups: interest and brand. All labels are returned (no truncation).

This API is exclusive to Advanced Plan users.

Privacy guard: to avoid identifying individuals when sample sizes are small, results are only returned when the link's lifetime unique click count is greater than 100. Otherwise, interest and brand will be returned as empty arrays.

Interest labels are returned as label IDs with audience counts. Refer to the interest label ID reference sheet for the human-readable label name of each ID.

Brand labels are returned as brand names with audience counts, reported in uppercase (e.g. PICSEE).

10 calls per second are allowed. If exceeded, a status code 429 will be returned. A try-catch structure is recommended to retry. Results are cached for 10 minutes.

Authorizations:
access_tokenX-API-KeyBearerAuth
path Parameters
encodeId
required
string
Example: 5b93x9

The slug of the short link

query Parameters
format
string
Enum: "json" "csv"
Example: format=csv

Supported return formats include "json" and "csv". If left blank, the default is "json". When csv is specified, interest and brand labels are merged into a single file with columns: type, label, count, where type is either interest or brand.

Responses

Request samples 

curl -X 'GET' \
'https://api.pics.ee/v4/links/5b93x9/details/audienceLabels?access_token=YOUR_ACCESS_TOKEN' \
-H 'accept: application/json'

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Authorized Security Partners Only

Endpoints exclusively available to authorized security partners.

Report Short Link Abuse

This API is exclusively available to authorized security partners. It enables partners to flag PicSee shortened URLs to display warning pages, preventing users from being redirected to potentially harmful destination sites.
Authorizations:
access_tokenX-API-KeyBearerAuth
Request Body schema: application/json
required
url
required
string <uri>

A PicSee short link - must include protocol (e.g., https) and path (e.g., /abuse)

attack_type
string

Type of attack - for internal reference

description
string

Notes - for internal reference

date
string <date>

Report date - for internal reference, used for report tracking

target_brand
string

Target brand - for internal reference

screenshot_url
string <uri>

Screenshot URL - for internal reference

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}