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

Authentication & Quickstart

Use a scoped API key, call one primary shorten endpoint, and keep every machine mutation tied to an organization, plan, and request trail.

Base path

/api/v1/*

Auth

Authorization: Bearer <api_key>

Primary lane

POST /api/v1/links/shorten

Machine context

Org, scopes, and plan are derived from the API key

Why this page exists

The external API is built for machine-to-machine traffic. Human administrators log into the dashboard to create keys and review usage; apps, agents, automations, and internal tools authenticate with scoped API keys against /api/v1/*.

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 /api/v1/* only for external callers. The dashboard continues to use session-based internal APIs.
Prefer narrow scopes per automation instead of handing every worker a wildcard key.
Use the public OpenAPI JSON when generating typed clients or external SDK stubs.

Rate limits and metering

Rate limits are plan-aware and enforced after API-key authentication succeeds.
Invalid or missing credentials are handled by separate anonymous-abuse limits.
The usage meter is subscription-level; per-key activity is tracked separately for portal visibility.

Error model

API_KEY_MISSING and API_KEY_INVALID are returned before the route touches tenant data.
API_SCOPE_FORBIDDEN means the key exists but does not include the scope that route requires.
PLAN_LIMIT_EXCEEDED means the organization is valid, but the current billing window has no remaining allowance for that metric.

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

Authentication & Quickstart

Use a scoped API key, call one primary shorten endpoint, and keep every machine mutation tied to an organization, plan, and request trail.

Base path

/api/v1/*

Auth

Authorization: Bearer <api_key>

Primary lane

POST /api/v1/links/shorten

Machine context

Org, scopes, and plan are derived from the API key

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 /api/v1/* only for external callers. The dashboard continues to use session-based internal APIs.
Prefer narrow scopes per automation instead of handing every worker a wildcard key.
Use the public OpenAPI JSON when generating typed clients or external SDK stubs.

Rate limits and metering

Rate limits are plan-aware and enforced after API-key authentication succeeds.
Invalid or missing credentials are handled by separate anonymous-abuse limits.
The usage meter is subscription-level; per-key activity is tracked separately for portal visibility.

Error model

API_KEY_MISSING and API_KEY_INVALID are returned before the route touches tenant data.
API_SCOPE_FORBIDDEN means the key exists but does not include the scope that route requires.
PLAN_LIMIT_EXCEEDED means the organization is valid, but the current billing window has no remaining allowance for that metric.

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

Quickstart request

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.

Authentication & Quickstart

Why this page exists

Headers

Request body fields

Request discipline

Create or rotate keys from the authenticated portal

Authentication & Quickstart

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.