generated: '2026-08-25'
method: searched
source: >-
  https://support.lucidlink.com/hc/en-us/articles/40235274774797-API-Key-Functionalities-Common-Automation-Scenarios,
  https://support.lucidlink.com/hc/en-us/articles/40222074543757-Getting-Started-with-Service-Accounts-API-Authentication,
  https://support.lucidlink.com/hc/en-us/articles/40222376164365-Best-Practices-Operating-the-LucidLink-API-Container,
  https://api.lucidlink.com/docs/api/v1/ (info.description), and openapi/lucidlink-service-api.json
description: >-
  Cross-cutting request/response semantics across LucidLink's three HTTP surfaces. The
  single most important fact for an integrator is that they are three different APIs with
  three different auth models, three different error envelopes and two different hosting
  models — the public Service API (LucidLink-hosted), the Management API (a Docker image
  the customer runs), and the v2 web service (LucidLink-hosted, unspecified).

surfaces:
- name: LucidLink Service API v1
  base_url: https://api.lucidlink.com/api/v1
  hosted_by: LucidLink
  spec: openapi/lucidlink-service-api.json
  note: >-
    The published info.description gives the base as https://api.lucidlink.com/v1 while the
    document's own basePath is /api/v1. Both were probed on 2026-08-25 and both routed
    (401 rather than 404), so the two forms appear to be aliases. basePath is treated as
    canonical here.
- name: LucidLink Management API v1
  base_url: http://{api-container-host}:3003/api/v1
  hosted_by: customer
  spec: not published — generated by the container at /api/v1/docs
- name: LucidLink Web Service API v2
  base_url: https://api.lucidlink.com/api/v2
  hosted_by: LucidLink
  spec: not published

api_style: REST over HTTPS, JSON request and response bodies, standard HTTP verbs

authentication:
  service_api_v1:
    scheme: OAuth2 client-credentials grant
    token_endpoint: https://auth.lucidlink.com/oauth2/token
    credential_issuance: >-
      Not self-service. The published reference says credentials are "provided upon request
      sent to support+ticket@lucidlink.com or by visiting https://support.lucidlink.com/hc/en-us".
    header: 'Authorization: <access_token>'
    header_note: >-
      LucidLink's own published example sends the raw access token with no Bearer prefix on
      the v1 Service API. Recorded as published.
  management_api_v1:
    scheme: Service-account secret key as a bearer token
    header: 'Authorization: Bearer <service key>'
    issuance: Workspace admin mints it in the Service Accounts tab; Business or Enterprise plan only.
    rotation: Multiple keys per service account; keys can be rotated without interrupting service.
    display: Credential is shown once, at generation or rotation.
    scope: 'For the initial release a service account inherits full workspace-administrator permissions — there is no least-privilege option.'
  web_service_v2:
    scheme: Service-account bearer token (documented prefix sa_live:)
    header: 'Authorization: Bearer sa_live:...'
  detail: authentication/lucidlink-authentication.yml

idempotency:
  supported: false
  mechanism: null
  evidence: >-
    No Idempotency-Key header, no idempotency section, and no retry-safety language appears
    anywhere in the published Swagger document, the API Overview, the endpoint reference,
    the service-account guide or the operating best-practices article. The best-practices
    article's guidance on repeated calls is "be respectful of the API" and "optimize batch
    operations" — advice about load, not about duplicate suppression.
  consequence: >-
    A retried POST /filespaces or POST /members after a timeout may create a second
    resource. The only safeguards published are 409 Conflict on createDomain,
    createFilespace and updateDomain, which makes a duplicate name safe but not a duplicate
    request in general.
  pointer_decision: >-
    No `Idempotency` pointer emitted in apis.yml. Emitting one would assert a retry-safety
    guarantee LucidLink does not publish.

pagination:
  style: limit-based
  supported_on: Management API directory listings only
  request_params:
    limit: 'Page size, e.g. GET /api/v1/filespaces/{filespaceId}/entries/{entryId}/children?limit=50. A default page size applies when omitted; the default value is not published.'
  response_fields: not published
  service_api_v1: >-
    None. getFilespaces, getDomains and getInvoices return unbounded arrays with no limit,
    cursor, offset or page parameter declared in the Swagger document.
  docs: https://support.lucidlink.com/hc/en-us/articles/40235274774797-API-Key-Functionalities-Common-Automation-Scenarios

field_expansion:
  supported: false

metadata:
  supported: false
  note: No user-defined metadata field is declared on any entity in the published spec.

request_tracing:
  supported: true
  mechanism: x-trace-id response header
  evidence: >-
    Observed on live api.lucidlink.com responses 2026-08-25 (e.g. x-trace-id:
    LxX3f2B8M00+f9z2HpDAv4MZt1lPUicn4gld). Undocumented — it is not mentioned in the Swagger
    document or any KB article, so an integrator would only find it by inspecting headers.

versioning:
  scheme: URL path version
  current: v1 (public Service API and Management API); v2 (unspecified web service)
  breaking_change_policy: not published
  container_versioning: >-
    The self-hosted Management API is versioned by Docker tag. LucidLink's best-practices
    article explicitly recommends pinning an explicit image tag rather than :latest "to
    control exactly when you upgrade, avoiding unexpected breaking changes or downtime" —
    which is the closest thing to a stated breaking-change posture LucidLink publishes, and
    it puts the responsibility on the operator.
  client_versioning: >-
    The desktop/filespace client is versioned by build number (e.g. build #8694) with dated
    release notes; see changelog/lucidlink-changelog.yml.

error_envelope:
  service_api_v1: '{"status": <int>, "message": <string>}'
  web_service_v2: '{"message": <string>, "error": <string>, "statusCode": <int>}'
  edge_unrouted: '{"success": false, "statusCode": <int>}'
  rfc9457: false
  error_codes: none published
  detail: errors/lucidlink-problem-types.yml

rate_limit_signaling:
  headers_published: false
  observed: >-
    api.lucidlink.com sends `access-control-expose-headers: Retry-After` on every response,
    which means Retry-After is intended to reach browser clients on some path — but no
    X-RateLimit-*, RateLimit-* or Retry-After header was present on any anonymous response
    observed on 2026-08-25.
  documented_position: >-
    "While there may not be hard external rate limits imposed by the self-hosted container,
    remember that the API calls still interact with your LucidLink backend services. Avoid
    aggressive polling."
  detail: rate-limits/lucidlink-rate-limits.yml

security_headers:
  observed_on: https://api.lucidlink.com
  headers:
  - strict-transport-security max-age=15552000; includeSubDomains
  - content-security-policy default-src 'self'
  - x-content-type-options nosniff
  - x-frame-options SAMEORIGIN
  - cross-origin-opener-policy same-origin
  - cross-origin-embedder-policy require-corp
  - cross-origin-resource-policy same-origin
  - referrer-policy no-referrer
  - x-permitted-cross-domain-policies none
  note: Helmet-style defaults, applied consistently. See security/lucidlink-domain-security.yml.

dry_run_mode:
  supported: false
  evidence: No preview, simulate, validate-only or dry-run parameter is declared on any operation in the published spec, and none is documented for the Management API.

reversibility:
  grade: documented
  grade_basis: >-
    Reversal paths exist and are documented for the destructive operations that matter, but
    LucidLink publishes no time window for any of them, so this cannot be graded verified.
    No window has been invented here.
  read_only_api: false
  surfaces:
  - operation: deleteFilespace
    api: LucidLink Service API v1
    operation_id: deleteFilespace
    reversal: none
    window: not stated
    note: >-
      No undo, restore or trash operation exists on the public Service API. Filespace
      deletion is documented as final and the KB advises backing up data before cancelling
      a subscription. Treat as irreversible.
  - operation: 'DELETE /api/v1/filespaces/{filespaceId} (Management API)'
    reversal: none
    window: not stated
    note: >-
      The endpoint reference marks this "Use with caution for decommissioning an old
      project space" — an explicit warning, not a reversal path.
  - operation: 'DELETE /api/v1/filespaces/{filespaceId}/entries/{entryId} (Management API, directory delete)'
    reversal: Filespace Snapshots
    reversal_mechanism: >-
      Manual or scheduled snapshots taken by a filespace administrator; recovery is
      performed at file, folder or filespace level from the LucidLink client, not through
      the API.
    window: >-
      Plan-dependent and stated only as a retention tier, not as an API-level window:
      Starter has no snapshots, Business retains 30 days, Enterprise is described as
      unlimited (https://www.lucidlink.com/pricing).
    docs: https://support.lucidlink.com/hc/en-us/sections/31125117603085-Administering-snapshots
    note: >-
      This is the strongest reversal LucidLink offers and it is real — the security page
      names ransomware and accidental overwrite as the intended cases. It is not exposed as
      an API operation, so an agent that deletes through the API cannot undo through the API.
  - operation: 'delete_path / write_file / edit_lines / search_replace / truncate_file / move_path (MCP tools)'
    api: LucidLink MCP Server
    reversal: Filespace Snapshots (out of band), plus dangerous-action confirmation and read-only mode as PREVENTION
    window: same plan-dependent snapshot retention as above
    note: >-
      The MCP server flags destructive operations for explicit client confirmation and
      offers a read-only mode, and it annotates every tool read_only / additive /
      destructive / stateful. Those stop an agent acting; they do not take an action back.
      No MCP tool restores, undeletes or rolls back.
  - operation: 'DELETE /api/v1/members/{memberId} (Management API)'
    reversal: re-invite
    window: not stated
    note: >-
      Removing a member revokes access; re-adding is a fresh POST /members and does not
      restore prior permissions. Under SCIM the reversible path is deactivation rather than
      deletion — a deactivated user keeps all permissions and configuration and regains
      access on reactivation in the IdP. That is a genuine reverse operation, but it is
      driven from the identity provider, not from the LucidLink API.
    docs: https://support.lucidlink.com/hc/en-us/articles/38861860730637-Understanding-SCIM-Integration-in-LucidLink
  - operation: 'DELETE /api/v1/filespaces/{filespaceId}/permissions/{permissionId} (Management API)'
    reversal: 'POST /api/v1/filespaces/{filespaceId}/permissions'
    window: 'not applicable — permissions are declarative state; re-granting fully restores'
    note: Permission changes are documented as taking effect in real time in both directions.
  - operation: unlink_external_file / unregister_data_store (LucidLink Connect, MCP + SDK)
    reversal: link_external_file / register_data_store
    window: not applicable
    note: >-
      Connect links are pointers to objects in the customer's own S3; unlinking removes the
      pointer, not the object, so relinking restores. This is the cleanly reversible corner
      of the surface.
  - operation: deleteDomain
    api: LucidLink Service API v1
    operation_id: deleteDomain
    reversal: createDomain
    window: not stated
    note: 409 Conflict guards deleting a domain that is still in use.

cross_references:
  errors: errors/lucidlink-problem-types.yml
  lifecycle: lifecycle/lucidlink-lifecycle.yml
  authentication: authentication/lucidlink-authentication.yml
  rate_limits: rate-limits/lucidlink-rate-limits.yml
  data_model: data-model/lucidlink-data-model.yml
  mcp: mcp/lucidlink-mcp.yml