Team API Encurtee
Integration via API key (Team API v1) and session-based REST for the app (/api/v1/teams). Same host (Nitro /api).
Overview
There are two families of endpoints: (1) Team API v1 for automation with an API key and a plan that includes API access; (2) /api/v1/teams routes with Supabase session cookies, used by the dashboard after login.
Where :id appears, it can be the internal team UUID or the numeric public_id (5–12 digits), except on routes that only list the current user’s teams.
Error and success messages follow the i18n_redirected cookie (pt or en) when the server translates them.
Two integration types
Team API v1
Prefix /api/v1/teams/:id. Authenticate with Authorization: Bearer or X-Team-Api-Key / X-Encurtee-Team-Key. Currently: GET ping and POST links (minimal body: url and optional title).
Session REST
Prefix /api/v1/teams (and /api/v1/teams/:id/…). Requires a logged-in user (same browser session: cookies). Permissions depend on team role (owner, admin, etc.).
:id parameter
Where :id is used, the route accepts UUID or numeric public_id resolved in the database.
Authentication — Team API v1
Applies to endpoints under /api/v1/teams/:id/ (recommended).
Authorization header (recommended)
Authorization: Bearer YOUR_FULL_API_KEYAlternative headers
X-Team-Api-Key or X-Encurtee-Team-Key with the key value.
When Authorization is sent
If Authorization is present, only a non-empty Bearer token is accepted (no X-* fallback).
Team API key model
Today there is one active key per team (stored as a hash). Rotating or revoking replaces or removes that key — useful for rotation and incident response.
Who manages it: members with edit_team (typically owner or admin). The key lets you automate calls without a browser session; treat it as a secret (do not commit to public repos).
Team API v1 — ping & links
Expand for parameters, query, and examples
Method | Path | Description | |
|---|---|---|---|
| GET | /api/v1/teams/:id/ping | Confirms the key for the team. Consumes team API usage tokens. | |
| POST | /api/v1/teams/:id/links | Creates a team link (owner as creator). URL validation and team-scoped duplicate checks. |
Authentication — session REST
Send Supabase session cookies (same as app $fetch with credentials: 'include'). Without a valid session, 401.
REST /api/v1/teams (session)
CRUD for teams, members, invites, listing/creating team links, API key management, and usage metrics. Permissions depend on your team role.
Expand for parameters, query, and examples
List and create teams
Method | Path | Description | Summary | |
|---|---|---|---|---|
| GET | /api/v1/teams | Lists teams you own or are an accepted member of; includes pending invites with invite_status. | — | |
| POST | /api/v1/teams | Creates a team; slug is derived from the name. Requires a plan that allows teams (e.g. Premium). | Body: ｛ "name": "Team name" ｝ |
Get, update, and delete a team
Method | Path | Description | Summary | |
|---|---|---|---|---|
| GET | /api/v1/teams/:id | Team detail if you are a member; includes is_owner, myRole, and permissions. | — | |
| PUT | /api/v1/teams/:id | Updates name, slug, and/or settings. Requires edit_team (owner or admin). | Body (optional): ｛ "name", "slug", "settings" ｝ | |
| DELETE | /api/v1/teams/:id | Deletes the team. Owner only. | — |
Members — list, invite, role, remove
Method | Path | Description | Summary | |
|---|---|---|---|---|
| GET | /api/v1/teams/:id/members | Lists members and invite states when applicable. | — | |
| POST | /api/v1/teams/:id/members | Invite by email (registered user). Requires invite_members. Roles: admin, moderator, user, viewer. | Body: ｛ "email": "…", "role?": "user" ｝ | |
| PUT | /api/v1/teams/:id/members/:userId | Change a member’s role. Not for the team owner. | Body: ｛ "role": "admin" | "moderator" | "user" | "viewer" ｝ | |
| DELETE | /api/v1/teams/:id/members/:userId | Remove a member (owner/admin) or leave the team (your own userId). Cannot remove the owner. | — |
Invites — accept
Method | Path | Description | Summary | |
|---|---|---|---|---|
| POST | /api/v1/teams/:id/accept-invite | The authenticated user accepts a pending invite to that team. | — |
Team links — list, create, update, and delete
Method | Path | Description | Summary | |
|---|---|---|---|---|
| GET | /api/v1/teams/:id/links | Lists team links with pagination. Requires view_links. | Query: page, limit (max 50), linkType, disabled | |
| POST | /api/v1/teams/:id/links | Creates a team link. With session: any member with create_link. With Team API v1 key (Bearer or X-*): same URL, minimal body (url required, optional title); link is attributed to the team owner. | Session: url (required), title?, linkType (default|temporary|premium), expirationType (clicks|time), expiresAt?, expireAfterClicks?. v1 key: url and optional title only. | |
| PUT | /api/v1/teams/:id/links/:linkId | Updates a team link (:linkId is the url_data UUID). Session: edit_link permission; same URL checks as creation (normalization, Safe Browsing when configured, duplicate within the team excluding this row) and the same linkType/temporary/premium rules as POST. v1 key: only url and/or title (at least one field in the body). | Session: optional url, title, linkType, expirationType, expiresAt, expireAfterClicks (same contract as POST). v1 key: ｛ url?, title? ｝. | |
| DELETE | /api/v1/teams/:id/links/:linkId | Soft-deletes the team link (deleted_at). Session: delete_link permission (or link owner). v1 key: API-enabled plan and valid key; link must belong to the team. | No body. v1 usage counts toward Team API token usage like other key-authenticated routes. |
Team API key — read, create, revoke
Method | Path | Description | Summary | |
|---|---|---|---|---|
| GET | /api/v1/teams/:id/api-key | Key state (hint, dates) and whether the plan allows API. Team member; management requires edit_team. | — | |
| POST | /api/v1/teams/:id/api-key | Generate or rotate the full key (shown once). Owner/admin + API-enabled plan. | — | |
| DELETE | /api/v1/teams/:id/api-key | Revoke the team key. Owner/admin. | — |
Usage (dashboard)
Method | Path | Description | Summary | |
|---|---|---|---|---|
| GET | /api/v1/teams/:id/usage-dashboard | Team stats: total and monthly links, members, monthly API tokens and rate policy. Does not include the owner’s personal plan URL quota. Team member. | — |
Common errors — Team API v1
HTTP | Situation | Description |
|---|---|---|
| 400 | Bad request | Missing id; missing url; URL validation; duplicate in team; etc. |
| 401 | v1 auth | Missing key, invalid Bearer, or revoked key. |
| 403 | Plan | Owner’s plan has no API access. |
| 404 | Team | Team not found or invalid :id. |
| 429 | Limits | Owner’s monthly link limit. |
| 500 | Server | Internal error. |
Common errors — session REST
HTTP | Situation | Description |
|---|---|---|
| 401 | Session | Not authenticated. |
| 403 | Permission / plan | No permission in team, member limit, or plan without API when managing the key. |
| 404 | Not found | Team, member, or user email not found. |
| 409 | Conflict | Team slug already used; invite/migration conflict. |
| 500 | Server | Internal error. |
cURL examples — Team API v1
Replace YOUR_API_KEY and TEAM_ID. The base URL is the one shown in the examples block (your public site).
For /api/v1/teams with session, curl needs the session cookie (copy from the browser) or use the app; it is not the same flow as the v1 key.
Ping
curl -s -H "Authorization: Bearer YOUR_API_KEY" "https://encurtee.me/api/v1/teams/TEAM_ID/ping"Create link (v1)
curl -s -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://example.com/path"}' "https://encurtee.me/api/v1/teams/TEAM_ID/links"New endpoints will be documented here as they ship.
The best platform to shorten URLs safely and efficiently.
Shorten, analyze and share your links with security and style.
Product