API and integration reference

Guides

Start here for auth and common semantics, then open the topic that matches what you are automating.

Base URL and versioning

All requests go to a single versioned base URL over TLS. Requests over plain HTTP are refused rather than redirected, so that credentials are never sent in the clear.

https://api.squidiphosting.com/v1

The version in the path changes only for breaking changes. Additive changes, such as new fields or new endpoints, are made within a version. Treat unknown fields as forward compatible and do not fail on encountering one.

Authentication

Authenticate with a bearer token in the Authorization header. Tokens are scoped to your account and carry a role that determines whether they can read only or also place orders and run lifecycle actions.

curl https://api.squidiphosting.com/v1/ports \
  -H "Authorization: Bearer sk_live_REPLACE_WITH_YOUR_KEY" \
  -H "Accept: application/json"

Calls without a valid token receive HTTP 401, a WWW-Authenticate: Bearer response header, and a JSON body:

{
  "error": "unauthorized",
  "message": "Missing or invalid Authorization header."
}

Tokens do not expire but can be revoked and rotated at any time. Rotate by creating a second token, cutting over, then revoking the first. Keep tokens out of source control and out of client-side code; a token is equivalent to your account credentials.

Invoices

GET /v1/invoices?status=open

{
  "data": [
    {
      "id": "inv_YYYY_MM_0412",
      "period": "YYYY-MM",
      "currency": "USD",
      "subtotal": 18400.00,
      "tax": 0.00,
      "total": 18400.00,
      "status": "open",
      "issued_at": "YYYY-MM-DD",
      "due_at": "YYYY-MM-DD"
    }
  ]
}

Amounts are decimal values in the stated currency. Line item detail is available at GET /v1/invoices/{id}.

Webhooks

Rather than polling, register an endpoint to receive events. Deliveries are signed with HMAC-SHA256 over the raw request body using your webhook secret, in the X-SIH-Signature header.

{
  "event": "port.state_changed",
  "id": "evt_9a3f7c21",
  "created_at": "YYYY-MM-DDTHH:MM:SSZ",
  "data": {
    "port_id": "prt_8f2c1a94",
    "previous_state": "provisioning",
    "state": "active"
  }
}

Events currently emitted:

• order.state_changed
• port.state_changed
• port.upgrade_completed
• circuit.state_changed
• node.state_changed
• node.reimage_completed
• usage.period_closed
• invoice.issued
• alert.triggered
• alert.resolved

Verify the signature before trusting a payload, and respond with a 2xx status within ten seconds. Failed deliveries are retried with exponential backoff for twenty-four hours. Deliveries may arrive more than once, so handle them idempotently using the event id.

Errors

Errors use standard HTTP status codes and a flat JSON body. The error field is a machine-readable string code; message is a human-readable explanation. Optional fields such as field and request_id appear when useful.

{
  "error": "validation_error",
  "message": "commit_mbps exceeds the capacity available at FRA",
  "field": "commit_mbps",
  "request_id": "req_7b2e9f14"
}

Always log request_id when present. It is the fastest way for our engineers to find the request in our logs.

Rate limits and pagination

• 120 requests per minute per token, returned in X-RateLimit-Remaining.
• Usage and metrics endpoints are limited to 20 requests per minute because the queries are expensive.
• List endpoints are cursor-paginated. Pass limit up to 200 and follow meta.next_cursor until it is null.
• Timestamps are RFC 3339 in UTC. Periods are YYYY-MM.
• Retry 429 and 5xx with exponential backoff and jitter.
• Always send an Idempotency-Key on POST that creates or mutates resources so retries are safe.

Integration support

Integration questions go to [email protected] with the request_id of a failing call. Partners in the Preferred tier and above can request a call with the engineer who maintains the API.