Public URL

Public tunnels and shareable URLs with optional custom domains.

Overview

Base path: https://api.infrai.cc/v1/public-url

Auth header: Authorization: Bearer $INFRAI_API_KEY

bash

# Call any /v1/public-url capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/public-url/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

Methods

public_url.create

POST /v1/public_url/create

Create a public URL or tunnel, optionally with a subdomain and TTL.

Parameters

Name	Type	Required	Description
`subdomain`	`string`	Optional	Requested subdomain.
`port`	`number`	Optional	Local port to expose.
`ttl_seconds`	`number`	Optional	Lifetime in seconds before expiry.
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

PublicUrlRecord { url_id, url, subdomain, state, created_at }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/public_url/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "report.txt", "text": "hello world", "expires_in": "7d", "max_downloads": 100}'

public_url.claim

POST /v1/public_url/claim/{id}

Claim an anonymous public URL into your account.

Parameters

Name	Type	Required	Description
`id`	`string`	Required	The public URL record id.

Returns

PublicUrlRecord

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/public_url/claim/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "..."}'

public_url.get

GET /v1/public_url/get/{id}

Fetch a public URL record by id.

Parameters

Name	Type	Required	Description
`id`	`string`	Required	The public URL record id.

Returns

PublicUrlRecord

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/public_url/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.domain.create

POST /v1/public_url/domain/create

Attach a custom domain for public URLs.

Returns

DomainRecord

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/public_url/domain/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "links.acme.com"}'

public_url.list

GET /v1/public_url/list

分页列出当前账户拥有的所有公开文件 URL

Parameters

Name	Type	Required	Description
`cursor`	`string`	Optional	分页游标，传入上一页返回的 next_cursor 以获取下一页
`limit`	`number`	Optional	单页返回的最大条数

Returns

Paginated<FileUrl> { items: FileUrl[], next_cursor }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/public_url/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.update

PATCH /v1/public_url/update/{id}

更新公开文件 URL 的访问控制（密码、下载次数上限、IP/地区白名单、限流、标签等）

Parameters

Name	Type	Required	Description
`id`	`string`	Required	要更新的公开 URL 的 url_id
`password`	`string`	Optional	访问密码；传 null 可清除已设置的密码
`max_downloads`	`number`	Optional	允许的最大下载次数
`ip_allowlist`	`string[]`	Optional	允许访问的 IP/CIDR 白名单
`geo_allowlist`	`string[]`	Optional	允许访问的国家/地区代码白名单
`rate_limit_rps`	`number`	Optional	每秒请求数限流上限（RPS）
`auth`	`object`	Optional	鉴权配置对象（如 Bearer/Basic）
`label`	`string`	Optional	便于识别的备注标签
`tags`	`Record<string, string>`	Optional	自定义键值标签
`idempotency_key`	`string`	Optional	幂等键，用于防止重试导致的重复写入

Returns

FileUrl

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X PATCH https://api.infrai.cc/v1/public_url/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "..."}'

public_url.extend

POST /v1/public_url/extend/{id}

延长公开文件 URL 的有效期，按小时追加

Parameters

Name	Type	Required	Description
`id`	`string`	Required	要延长的公开 URL 的 url_id
`additional_hours`	`number`	Required	在当前到期时间基础上追加的小时数
`idempotency_key`	`string`	Optional	幂等键，用于防止重试导致的重复延长

Returns

FileUrl

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/public_url/extend/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "...", "additional_hours": 0}'

public_url.disable

POST /v1/public_url/disable/{id}

停用一个公开文件 URL，使其立即不可访问

Parameters

Name	Type	Required	Description
`id`	`string`	Required	要停用的公开 URL 的 url_id
`idempotency_key`	`string`	Optional	幂等键，用于防止重试导致的重复操作

Returns

FileUrl

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/public_url/disable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

public_url.delete

DELETE /v1/public_url/delete/{id}

永久删除一个公开文件 URL

Parameters

Name	Type	Required	Description
`id`	`string`	Required	要删除的公开 URL 的 url_id
`idempotency_key`	`string`	Optional	幂等键，用于防止重试导致的重复删除

Returns

void

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/public_url/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.stats

GET /v1/public_url/stats/{id}

查询公开文件 URL 的访问统计：带宽、请求数、延迟分位与状态码分布

Parameters

Name	Type	Required	Description
`id`	`string`	Required	要查询统计的公开 URL 的 url_id

Returns

UrlStats { url_id, period, bandwidth_used_gb, access_count, p99_latency_ms, breakdown }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/public_url/stats/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.events

GET /v1/public_url/events/{id}

分页查询公开文件 URL 的访问事件流

Parameters

Name	Type	Required	Description
`id`	`string`	Required	要查询事件的公开 URL 的 url_id
`cursor`	`string`	Optional	分页游标，传入上一页返回的 next_cursor 以获取下一页
`limit`	`number`	Optional	单页返回的最大事件数

Returns

Paginated<AccessEvent> { items: AccessEvent[], next_cursor }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/public_url/events/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.retention.get

GET /v1/public_url/retention/get/{id}

查询公开文件 URL 的留存策略

Parameters

Name	Type	Required	Description
`id`	`string`	Required	要查询留存策略的公开 URL 的 url_id

Returns

RetentionPolicy { url_id, retention_days, delete_after }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/public_url/retention/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.retention.set

POST /v1/public_url/retention/set/{id}

设置公开文件 URL 的留存天数与到期删除策略

Parameters

Name	Type	Required	Description
`id`	`string`	Required	要设置留存策略的公开 URL 的 url_id
`retention_days`	`number`	Required	留存天数，到期后自动删除
`idempotency_key`	`string`	Optional	幂等键，用于防止重试导致的重复设置

Returns

RetentionPolicy { url_id, retention_days, delete_after }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/public_url/retention/set/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "...", "days": 0}'

public_url.domain.get

GET /v1/public_url/domain/get/{domain}

查询单个自定义域名的状态、验证与证书信息

Parameters

Name	Type	Required	Description
`domain`	`string`	Required	要查询的自定义域名

Returns

Domain { domain, label, status, verified_at, cert_expires_at }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/public_url/domain/get/DOMAIN \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.domain.list

GET /v1/public_url/domain/list

分页列出账户已添加的自定义域名

Parameters

Name	Type	Required	Description
`cursor`	`string`	Optional	分页游标，传入上一页返回的 next_cursor 以获取下一页
`limit`	`number`	Optional	单页返回的最大域名数

Returns

Paginated<Domain> { items: Domain[], next_cursor }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/public_url/domain/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.domain.verify

POST /v1/public_url/domain/verify

触发自定义域名的归属验证与证书签发

Parameters

Name	Type	Required	Description
`domain`	`string`	Required	要验证的自定义域名

Returns

VerifyResult { domain, verified, verified_at, cert_issuer, reason }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/public_url/domain/verify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "links.acme.com"}'

public_url.domain.delete

DELETE /v1/public_url/domain/delete/{domain}

删除一个自定义域名

Parameters

Name	Type	Required	Description
`domain`	`string`	Required	要删除的自定义域名
`idempotency_key`	`string`	Optional	幂等键，用于防止重试导致的重复删除

Returns

void

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/public_url/domain/delete/DOMAIN \
  -H "Authorization: Bearer $INFRAI_API_KEY"

All capabilities

Every routed capability in this module — the complete public REST contract. The methods above are the guided walkthrough; this index is the full reference.

Capability	Endpoint	Description
`public_url.claim`	`POST /v1/public_url/claim/{id}`	Claim an unbound (device-state) public URL onto the calling bound account; idempotent for URLs you already own.
`public_url.create`	`POST /v1/public_url/create`	Upload content and instantly get a public download URL with full access control in a single step.
`public_url.delete`	`DELETE /v1/public_url/delete/{id}`	Delete a public file URL permanently.
`public_url.disable`	`POST /v1/public_url/disable/{id}`	Disable a public file URL, making it immediately inaccessible.
`public_url.domain.create`	`POST /v1/public_url/domain/create`	Register a custom domain for hosting public URLs, returning the DNS records to publish (distinct from email sender domains — see email.domain.*).
`public_url.domain.delete`	`DELETE /v1/public_url/domain/delete/{domain}`	Delete a custom domain (distinct from email sender domains — see email.domain.*).
`public_url.domain.get`	`GET /v1/public_url/domain/get/{domain}`	Get a custom domain's status, verification, and certificate details (distinct from email sender domains — see email.domain.*).
`public_url.domain.list`	`GET /v1/public_url/domain/list`	List the account's custom domains with pagination (distinct from email sender domains — see email.domain.*).
`public_url.domain.verify`	`POST /v1/public_url/domain/verify`	Trigger ownership verification and certificate issuance for a custom domain (distinct from email sender domains — see email.domain.*).
`public_url.events`	`GET /v1/public_url/events/{id}`	List a public file URL's access-event stream (source IP/region/UA, status codes, lifecycle actions) with pagination.
`public_url.extend`	`POST /v1/public_url/extend/{id}`	Extend a public file URL's expiry by additional hours.
`public_url.get`	`GET /v1/public_url/get/{id}`	Retrieve a public URL's metadata and status by ID.
`public_url.list`	`GET /v1/public_url/list`	List all public file URLs owned by the account with pagination.
`public_url.retention.get`	`GET /v1/public_url/retention/get/{id}`	Get the retention policy for public file URLs.
`public_url.retention.set`	`POST /v1/public_url/retention/set/{id}`	Set the retention days and expiry-deletion policy for public file URLs.
`public_url.stats`	`GET /v1/public_url/stats/{id}`	Query public file URL access statistics: bandwidth, request count, latency percentiles, and status-code distribution.
`public_url.update`	`PATCH /v1/public_url/update/{id}`	Update a public file URL's access controls: password, max-downloads, IP/geo allowlists.

End-to-end example

A production-style walkthrough of this module: configure once, then run the flow. It exercises most of the module's APIs.

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at the console for a project key
#    + $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
#    POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."   # from the console


# 2) public_url.create
curl -X POST https://api.infrai.cc/v1/public_url/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "report.txt", "text": "hello world", "expires_in": "7d", "max_downloads": 100}'

# 3) public_url.claim
curl -X POST https://api.infrai.cc/v1/public_url/claim/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "..."}'

# 4) public_url.get
curl -X GET https://api.infrai.cc/v1/public_url/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 5) public_url.domain.create
curl -X POST https://api.infrai.cc/v1/public_url/domain/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "links.acme.com"}'

# 6) public_url.list
curl -X GET https://api.infrai.cc/v1/public_url/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 7) public_url.update
curl -X PATCH https://api.infrai.cc/v1/public_url/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "..."}'

# 8) public_url.extend
curl -X POST https://api.infrai.cc/v1/public_url/extend/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "...", "additional_hours": 0}'

# 9) public_url.disable
curl -X POST https://api.infrai.cc/v1/public_url/disable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'