Skip to API content
Birdor API v1

API reference · v1

Strip tracking parameters from URLs

Remove tracking parameters from up to 100 URLs and normalize them: lowercase host, default port removed, empty query segments dropped, optional parameter sorting and fragment removal. The parameters that remain are kept byte-for-byte (no re-encoding), so signed and encoding-sensitive links keep working. Built-in list (46 names): utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_id, utm_source_platform, utm_creative_format, utm_marketing_tactic, gclid, gclsrc, dclid, gbraid, wbraid, fbclid, msclkid, twclid, ttclid, igshid, yclid, mc_cid, mc_eid, _ga, _gl, ref, ref_src, refsrc, vero_id, vero_conv, mkt_tok, oly_anon_id, oly_enc_id, scid, sc_cid, epik, hsa_acc, hsa_cam, hsa_grp, hsa_ad, hsa_src, hsa_tgt, hsa_kw, hsa_mt, hsa_net, hsa_ver, spm. Requires a credential with tools.run; every accepted call consumes one monthly unit, including business 4xx/5xx.

POST/v1/run/url/clean

Access requirements

Health, metadata, changelog and waitlist routes are public. Catalog reads (GET /v1/tools, /v1/tools/{id}, /v1/colors/*) and POST /v1/tools/query require a tools.read credential; POST /v1/run/* requires tools.run. There is no anonymous access to these routes: send an API key (Bearer OR X-API-Key) from your server, or use the HttpOnly main-site session plus workspace selection and same-origin Origin. Never combine credentials. Every admitted call is metered. Ingress and workspace/actor minute/month limits are separate; waitlist has its own policy.

Implemented interfaces and development screens do not imply public production availability, paid access or a completed payment integration. Confirm access with Birdor before connecting an application. No paid Pro service, activation or cross-device sync is currently delivered. We are validating one repeatable task before building a paid offer.

Parameters

FieldDescription
AuthorizationstringOptionalBearer API key with tools.run; alternatively X-API-Key. One of the credentials is required.
X-API-KeystringOptionalAlternative to Authorization; never send both.
X-Birdor-Workspace-IDstringOptionalRequired with the site session; optional and matching with an API key.
X-Birdor-Project-IDstringOptionalOptional owned project; a project-bound key cannot select another project.

Request body

Send JSON with Content-Type: application/json.

FieldDescription
urlsarrayRequiredURLs to clean, 1–100 entries of at most 2048 characters. A missing scheme defaults to https; only http and https are accepted. Invalid entries are reported per item.
removeParamsarrayOptionalExtra parameter names to strip (case-insensitive), on top of the built-in list of utm_*, gclid, fbclid, msclkid, mc_cid, _ga, ref and other tracking parameters.
keepParamsarrayOptionalBuilt-in parameter names to keep (case-insensitive), e.g. ["ref"] for GitHub links.
sortParamsbooleanOptionalSort the remaining parameters by name for stable cache keys or comparisons; default false.
removeFragmentbooleanOptionalDrop the #fragment; default false.

Request example

1. Set the base URL

Request example
curl --request POST "$BIRDOR_API_BASE_URL/v1/run/url/clean" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $BIRDOR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "urls": [
    "https://Example.com:443/pricing?plan=pro&utm_source=newsletter&utm_medium=email&fbclid=IwAR0x#faq",
    "github.com/acme/app/blob/main/README.md?ref=main"
  ],
  "keepParams": [
    "ref"
  ]
}'

Examples are copied only; this page does not send API requests.

Responses

Illustrative response. Values vary by environment and time.

200Success
HTTP 200
{
  "ok": true,
  "data": {
    "results": [
      {
        "input": "https://Example.com:443/pricing?plan=pro&utm_source=newsletter&utm_medium=email&fbclid=IwAR0x#faq",
        "ok": true,
        "url": "https://example.com/pricing?plan=pro#faq",
        "changed": true,
        "removedParams": [
          {
            "key": "utm_source",
            "value": "newsletter"
          },
          {
            "key": "utm_medium",
            "value": "email"
          },
          {
            "key": "fbclid",
            "value": "IwAR0x"
          }
        ],
        "error": null
      },
      {
        "input": "github.com/acme/app/blob/main/README.md?ref=main",
        "ok": true,
        "url": "https://github.com/acme/app/blob/main/README.md?ref=main",
        "changed": true,
        "removedParams": [],
        "error": null
      }
    ],
    "removedCount": 3
  },
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
400Invalid JSON, schema validation failure (field paths/codes only, never input values) or ambiguous credentials
HTTP 400
{
  "ok": false,
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
401Missing, expired, rotated, revoked or invalid credential; there is no anonymous access
HTTP 401
{
  "ok": false,
  "code": "UNAUTHENTICATED",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
403Key lacks tools.run, or workspace/project/member policy or site Origin denied
HTTP 403
{
  "ok": false,
  "code": "FORBIDDEN",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
405Only POST is supported; rejected before admission
HTTP 405
{
  "ok": false,
  "code": "METHOD_NOT_ALLOWED",
  "message": "Method not allowed",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
408Body read exceeds five seconds; before admission
HTTP 408
{
  "ok": false,
  "code": "REQUEST_TIMEOUT",
  "message": "Request body timeout or aborted",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
413Body exceeds 32768 bytes; before admission
HTTP 413
{
  "ok": false,
  "code": "PAYLOAD_TOO_LARGE",
  "message": "Request body too large",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
415Content-Type must be application/json; before admission
HTTP 415
{
  "ok": false,
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "message": "JSON content type required",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
429Ingress, workspace/actor minute or monthly quota exceeded; inspect code and Retry-After
HTTP 429
{
  "ok": false,
  "code": "QUOTA_EXCEEDED",
  "message": "API request limit exceeded",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
500Unexpected operation failure; details are never echoed
HTTP 500
{
  "ok": false,
  "code": "OPERATION_FAILED",
  "message": "Operation failed",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
503Authentication/metering dependency unavailable
HTTP 503
{
  "ok": false,
  "code": "API_GATEWAY_UNAVAILABLE",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
Error handling

Example response fields

Fields shown in this example; optional fields can be omitted. Array rows describe the first example element.

okboolean
Application success flag.
dataobject
Endpoint-specific result.
data.resultsarray
Endpoint-specific example value.
data.results[].inputstring
Endpoint-specific example value.
data.results[].okboolean
Application success flag.
data.results[].urlstring
Endpoint-specific example value.
data.results[].changedboolean
Endpoint-specific example value.
data.results[].removedParamsarray
Endpoint-specific example value.
data.results[].errornull
Validator error details.
data.removedCountnumber
Endpoint-specific example value.
request_idstring
Origin-response identifier matching X-Request-ID; a shared HTTP cache may replay the original trace.
timestampstring
Response creation timestamp.