API Operational

v1 stable

Operational

Reference docs
for the machine‑auth
link API.

Operator-first surface for API-key auth, endpoint behavior, request schemas, error codes, and same-origin live testing.

4 endpoints

<50ms p99

Bearer auth

OpenAPI-backed

POST /api/v1/links/shorten

# Request

curl -X POST \

"https://1get.site/api/v1/links/shorten" \

-H "Authorization: Bearer 1gt_live_••••••••" \

-H "Content-Type: application/json" \

-d '{ "url": "https://example.com/very-long-path"}'

# 201 Created

{

"data": {

"id": "lnk_01jf8x2a4m...",

"short_url": "https://1get.site/my-link",

"clicks": 0

}

Current page

Shorten link and return QR metadata

Create a short link for your organization and return QR metadata in the same response.

Route

POST

/api/v1/links/shorten

Auth

Scoped API key

Required scopes

links:write

Plan lane

Requires an API-enabled paid plan. Basic supports default QR output; richer QR customization requires Business or higher.

Response envelope

`{ data: ... }` with stable error codes on failures

Why this page exists

This is the primary machine-to-machine endpoint for applications, agents, automations, and internal tools. It reuses 1get link creation logic, supports idempotent retries, and returns the absolute short URL plus QR metadata without requiring a follow-up call.

Request reference

Headers

Field	Type	Required	Description	Example
Authorization	string	Optional	Preferred authentication header. Send a scoped API key using the Bearer scheme.	Bearer 1gt_live_1234567890abcdef
X-API-Key	string	Optional	Alternative authentication header. Use this only when Authorization headers are difficult to inject.	1gt_live_1234567890abcdef
X-Request-Id	string	Optional	Optional caller-provided correlation ID. When omitted, 1get generates one and echoes it back in responses.	req_a1f7f4bf
Idempotency-Key	string	Optional	Recommended for safe retries on POST /links/shorten. Reusing a key with a different payload returns IDEMPOTENCY_CONFLICT.	idem_launch_job_001

Request body fields

Field	Type	Required	Description	Example
original_url	string	Required	Destination URL to shorten.	https://example.com/product/launch?ref=campaign
custom_slug	string \| null	Optional	Optional custom slug. 3-50 characters using letters, numbers, hyphens, and underscores.	launch-2026
expires_at	string \| null	Optional	Optional future expiry timestamp.	2026-07-01T00:00:00.000Z
password	string \| null	Optional	Optional password for protected redirects.	null
max_clicks	integer \| null	Optional	Optional click cap.	—
redirect_type	PERMANENT_301 \| TEMPORARY_302	Optional	—	TEMPORARY_302
tags	string[]	Optional	Optional tags. Maximum 10.	["launch","email"]
utm_source	string	Optional	Optional UTM source override.	newsletter
utm_medium	string	Optional	Optional UTM medium override.	email
utm_campaign	string	Optional	Optional UTM campaign override.	launch
utm_term	string \| null	Optional	Optional UTM term override.	null
utm_content	string \| null	Optional	Optional UTM content override.	null
qr	object	Optional	QR generation preferences. Default PNG/256/black-on-white is included on API-enabled paid plans.	—
qr.include	boolean	Required	Whether to return QR metadata in the response.	true
qr.format	PNG \| SVG	Required	—	PNG
qr.size	integer	Required	QR size in pixels.	256
qr.foreground_color	string	Required	6-digit hex foreground color.	#000000
qr.background_color	string	Required	6-digit hex background color.	#FFFFFF

Request discipline

Use custom_slug only when the plan and slug policy allow it.
The default QR payload is safe on API-enabled paid plans. Richer QR customization is a higher-plan lane.
Tenant context is always resolved from the API key. Do not send organization ids in your client payloads.

Rate limits and metering

Shorten traffic is the highest-impact write lane, so it is the rate limit to budget first.
When the monthly api_calls limit is exhausted, the route returns PLAN_LIMIT_EXCEEDED before writing a new link.
A 429 response means the current minute-level rate limit is saturated even if monthly quota remains.

Error model

VALIDATION_FAILED surfaces field-level request issues such as malformed URLs or invalid QR options.
CONFLICT is used for state conflicts such as a slug that is already taken.
API_SCOPE_FORBIDDEN means the key can authenticate but lacks links:write.

API_KEY_MISSING

API_KEY_INVALID

API_SCOPE_FORBIDDEN

API_ACCESS_DISABLED

RATE_LIMITED

VALIDATION_FAILED

PLAN_LIMIT_EXCEEDED

CONFLICT

IDEMPOTENCY_CONFLICT

IDEMPOTENCY_IN_PROGRESS

Next surface

Create or rotate keys from the authenticated portal

Use the dashboard portal when you need scoped key lifecycle management, entitlement visibility, and request activity history.

Open API Access OpenAPI JSON

Shorten link and return QR metadata

Create a short link for your organization and return QR metadata in the same response.

Route

POST

/api/v1/links/shorten

Auth

Scoped API key

Required scopes

links:write

Plan lane

Requires an API-enabled paid plan. Basic supports default QR output; richer QR customization requires Business or higher.

Response envelope

`{ data: ... }` with stable error codes on failures

Why this page exists

Request reference

Headers

Field	Type	Required	Description	Example
Authorization	string	Optional	Preferred authentication header. Send a scoped API key using the Bearer scheme.	Bearer 1gt_live_1234567890abcdef
X-API-Key	string	Optional	Alternative authentication header. Use this only when Authorization headers are difficult to inject.	1gt_live_1234567890abcdef
X-Request-Id	string	Optional	Optional caller-provided correlation ID. When omitted, 1get generates one and echoes it back in responses.	req_a1f7f4bf
Idempotency-Key	string	Optional	Recommended for safe retries on POST /links/shorten. Reusing a key with a different payload returns IDEMPOTENCY_CONFLICT.	idem_launch_job_001

Request body fields

Field	Type	Required	Description	Example
original_url	string	Required	Destination URL to shorten.	https://example.com/product/launch?ref=campaign
custom_slug	string \| null	Optional	Optional custom slug. 3-50 characters using letters, numbers, hyphens, and underscores.	launch-2026
expires_at	string \| null	Optional	Optional future expiry timestamp.	2026-07-01T00:00:00.000Z
password	string \| null	Optional	Optional password for protected redirects.	null
max_clicks	integer \| null	Optional	Optional click cap.	—
redirect_type	PERMANENT_301 \| TEMPORARY_302	Optional	—	TEMPORARY_302
tags	string[]	Optional	Optional tags. Maximum 10.	["launch","email"]
utm_source	string	Optional	Optional UTM source override.	newsletter
utm_medium	string	Optional	Optional UTM medium override.	email
utm_campaign	string	Optional	Optional UTM campaign override.	launch
utm_term	string \| null	Optional	Optional UTM term override.	null
utm_content	string \| null	Optional	Optional UTM content override.	null
qr	object	Optional	QR generation preferences. Default PNG/256/black-on-white is included on API-enabled paid plans.	—
qr.include	boolean	Required	Whether to return QR metadata in the response.	true
qr.format	PNG \| SVG	Required	—	PNG
qr.size	integer	Required	QR size in pixels.	256
qr.foreground_color	string	Required	6-digit hex foreground color.	#000000
qr.background_color	string	Required	6-digit hex background color.	#FFFFFF

Request discipline

Use custom_slug only when the plan and slug policy allow it.
The default QR payload is safe on API-enabled paid plans. Richer QR customization is a higher-plan lane.
Tenant context is always resolved from the API key. Do not send organization ids in your client payloads.

Rate limits and metering

Shorten traffic is the highest-impact write lane, so it is the rate limit to budget first.
When the monthly api_calls limit is exhausted, the route returns PLAN_LIMIT_EXCEEDED before writing a new link.
A 429 response means the current minute-level rate limit is saturated even if monthly quota remains.

Error model

VALIDATION_FAILED surfaces field-level request issues such as malformed URLs or invalid QR options.
CONFLICT is used for state conflicts such as a slug that is already taken.
API_SCOPE_FORBIDDEN means the key can authenticate but lacks links:write.

API_KEY_MISSING

API_KEY_INVALID

API_SCOPE_FORBIDDEN

API_ACCESS_DISABLED

RATE_LIMITED

VALIDATION_FAILED

PLAN_LIMIT_EXCEEDED

CONFLICT

IDEMPOTENCY_CONFLICT

IDEMPOTENCY_IN_PROGRESS

Next surface

Create or rotate keys from the authenticated portal

Use the dashboard portal when you need scoped key lifecycle management, entitlement visibility, and request activity history.

Open API Access OpenAPI JSON

Request lab

Shorten link and return QR metadata

Edit the API key locally, tune the request payload, and copy a real cURL command.

POST

API key

Stored in this browser only for docs convenience. It is only sent if you click “Try request”.

Payload JSON

cURL

Copy a request that matches your current edits

curl -X POST "https://1get.site/api/v1/links/shorten" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "X-Request-Id: docs_post_links_shorten" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-post-links-shorten-0" \
  -d '{
  "original_url": "https://example.com/product/launch?ref=campaign",
  "custom_slug": "launch-2026",
  "redirect_type": "TEMPORARY_302",
  "tags": [
    "launch",
    "email"
  ],
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "launch",
  "qr": {
    "include": true,
    "format": "PNG",
    "size": 256,
    "foreground_color": "#000000",
    "background_color": "#FFFFFF"
  }
}'

Request headers

Authorization

Bearer <YOUR_API_KEY>

X-Request-Id

docs_post_links_shorten

Content-Type

application/json

Idempotency-Key

docs-post-links-shorten-0

`X-API-Key` is supported as an alternative auth header, but the request lab uses the bearer header by default.

Examples

Success and failure contracts

201 response

{
  "data": {
    "id": "ecb3ec1f-ae2e-4c30-b7d6-c47b4c671f7b",
    "slug": "launch-2026",
    "short_url": "https://1get.site/launch-2026",
    "original_url": "https://example.com/product/launch?ref=campaign",
    "status": "ACTIVE",
    "redirect_type": "TEMPORARY_302",
    "expires_at": null,
    "max_clicks": null,
    "total_clicks": 0,
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "launch",
    "utm_term": null,
    "utm_content": null,
    "tags": [
      "launch",
      "email"
    ],
    "password_protected": false,
    "created_at": "2026-04-06T07:10:02.000Z",
    "updated_at": "2026-04-06T07:10:02.000Z",
    "qr_status": "ready",
    "qr_code": {
      "id": "5af01dc0-f2ff-45dd-a9df-9787644b3f54",
      "url": "https://1get.site/uploads/qr/launch-2026.png",
      "format": "PNG",
      "size": 256,
      "foreground_color": "#000000",
      "background_color": "#FFFFFF",
      "logo_url": null,
      "created_at": "2026-04-06T07:10:02.000Z",
      "updated_at": "2026-04-06T07:10:02.000Z"
    }
  }
}

Live runner

Same-origin request testing

Disabled by default. The request preview below is exactly what will be sent if you opt in.

{
  "method": "POST",
  "url": "https://1get.site/api/v1/links/shorten",
  "headers": {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "X-Request-Id": "docs_post_links_shorten",
    "Content-Type": "application/json",
    "Idempotency-Key": "docs-post-links-shorten-0"
  },
  "body": {
    "original_url": "https://example.com/product/launch?ref=campaign",
    "custom_slug": "launch-2026",
    "redirect_type": "TEMPORARY_302",
    "tags": [
      "launch",
      "email"
    ],
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "launch",
    "qr": {
      "include": true,
      "format": "PNG",
      "size": 256,
      "foreground_color": "#000000",
      "background_color": "#FFFFFF"
    }
  }
}

Enable the runner when you want to send the request to your own 1get deployment from this page.

Discovery

Move from docs into plans, portal access, and product context

Use the surrounding public surfaces to compare plan lanes, see the developer bridge page, or move into the authenticated API Access portal when you are ready to create real keys.

Homepage

Positioning, API summary, privacy-first analytics, Bitly-alternative framing, and pricing overview.

Developers

Public developer bridge page with API-key auth model, request shapes, QR support, and upgrade path.

Guides

Implementation Guides

Long-form technical guides for Next.js, Python, AI agents, automations, and Bitly migration flows built around the public API surface.

Pricing

Plan ladder for Free, Basic, Business, and Enterprise with API-adjacent positioning and FAQ.

Affiliate Program

Partner-program overview for agencies, creators, consultants, and technical partners.

Bitly Alternative

Comparison page for developers evaluating 1get vs Bitly on API approach, speed, privacy, and auditability.

Use Cases

How developers, consultancies, marketing teams, and content creators use 1get — API automation, link analytics, and multi-client workspaces.

Reference docsfor the machine‑authlink API.

Shorten link and return QR metadata

Why this page exists

Headers

Request body fields

Request discipline

Create or rotate keys from the authenticated portal

Shorten link and return QR metadata

Why this page exists

Headers

Request body fields

Request discipline

Create or rotate keys from the authenticated portal

Move from docs into plans, portal access, and product context

Reference docs
for the machine‑auth
link API.