Help Center›Channels›Public API

FyneDesk Public API

Connect FyneDesk to the systems your team already uses. The REST API gives Business teams a governed way to sync service data, build reporting, automate repeatable work, and migrate records without duplicate entry.

What you can build

The FyneDesk API uses JSON over HTTPS at https://api.fynedesk.ai/v1. It covers the records around the full service lifecycle: tickets and conversations, contacts and companies, agents and teams, assets, knowledge, time entries, satisfaction data, events, imports, webhooks, and calendar data.

You might use it to create tickets from another system, keep customer and asset records in sync, build internal reporting, preserve source history during a migration, or connect FyneDesk to a workflow your team already depends on.

Use the in app reference for implementation detailsThe public OpenAPI specification is the source of truth for current endpoint paths, request fields, response fields, and scopes. This guide explains the main capabilities and safe operating patterns.

Who can use the Public API

Creating and managing API keys requires the Business plan and an authorized workspace Admin. Admins create keys in Admin Settings → Developer & Data → API Keys, choose the smallest required scopes, and can revoke or replace a key without sharing it with FyneDesk support.

Quick start

  1. 1Open Admin Settings → Developer & Data → API Keys in a Business workspace.
  2. 2Create a key with a clear name, such as "Reporting connection" or "Customer sync".
  3. 3Choose only the scopes the integration needs and set an expiry that fits its purpose.
  4. 4Copy the key and store it in your secret manager. FyneDesk shows the full value only once.
  5. 5Call GET /me first to confirm the workspace, scopes, rate limit, and supported enum values.
Keep the key somewhere safeStore the value shown at creation in a secret manager. Do not paste an API key into FyneBot, a support ticket, source control, browser code, screenshots, or logs. If a key is exposed or lost, revoke it and create a replacement.

Authentication

Send your API key with every request as a bearer token:

curl https://api.fynedesk.ai/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Use a placeholder in documentation and examples—never a live key. Responses are JSON. Errors include a stable code, human-readable message, optional field details, and a request ID that support can use without needing your credential.

Choose the right scopes

Scopes follow a simple resource:action format. Give each key the smallest set of permissions it needs.

  • read lets an integration view data.
  • write lets an integration create and update data.
  • delete is separate because removing records is destructive. It is never included with write access.

Available scopes cover tickets, contacts, companies, articles, assets, time entries, users, metadata, events, imports, webhooks, and calendar data. For example, a reporting connection may need only tickets:read, while a customer sync might need contacts:read and contacts:write.

Start with less accessKeep delete scopes off unless the integration truly needs to remove records. A narrowly scoped key limits the impact of a configuration mistake or exposed secret.

What the API can access

  • Tickets and conversations can be listed, searched, created, updated, commented on, assigned, tagged, and related to people or companies.
  • Contacts and companies can be read, created, updated, and deleted.
  • Knowledge base articles can be read, created, and updated.
  • Agents and teams expose the ownership structure integrations need for routing and reporting.
  • Assets can be read, created, and updated, including custom fields and relationships.
  • Time and satisfaction support reporting across work logs and customer feedback.
  • Events, imports, webhooks, metadata, and calendar data support durable sync, migrations, discovery, and automation.

The API Reference shows the exact operations and scopes for each resource.

Make changes safely

Use an Idempotency-Key header on create requests. This lets your integration retry safely after a network problem without accidentally creating duplicate records. For updates, send If-Match with the current version so one writer does not silently overwrite another.

FyneDesk accepts only approved writable fields. Relationship fields, such as an assignee or category, are checked to make sure they belong to the same workspace.

Every API change is recorded in the ticket activity history, just like a change made in the FyneDesk interface. Tickets created through the API are also marked as API sourced.

Pagination, limits, and errors

List responses use cursor pagination. For long-running exports or data warehouses, use stable sync mode and save the returned cursor. The events feed lets a sync observe deletions that a normal list can no longer return.

The current default rate limit is 120 requests per minute per key and can be customized per key. FyneDesk returns limit, remaining, and reset details with requests. If a key goes over its limit, the API returns HTTP 429. Treat the live headers as the source of truth.

Common response statuses include 200 and 201 for success, 400 for an invalid request, 401 for an invalid key, 403 for a missing permission, 404 when a record cannot be found, 429 for rate limiting, and 500 for an unexpected error.

Use webhooks for real time events

The API is useful when your system needs to request or change FyneDesk data. Outbound webhooks are useful when your system needs FyneDesk to tell it that something happened.

Webhooks can send signed events for ticket, contact, and company activity to your HTTPS endpoint. FyneDesk also supports managed webhook destinations for HubSpot and Zulip. Delivery logs, test events, redelivery, and automatic disabling after repeated failures help you operate integrations with confidence.

Webhooks are available on Pro and Business. Learn more in Webhooks & Integrations.

Move files and historical data

Attachments use a direct signed-upload flow: request an upload, send the file to the signed URL, then confirm it before attaching it to a record. The default maximum file size is 25 MB.

Migration endpoints can preserve original timestamps and authorship without making live comments impersonate another user. Import jobs are built to resume safely after interruption, which makes them a better fit than replaying years of history through live ticket endpoints.

Deliberate safety limits

  • Live comments use the authenticated API identity; historical author and date preservation belongs in migration jobs.
  • Satisfaction ratings are read-only.
  • Knowledge articles created through the API begin as drafts and require a human publishing step.
  • Article and asset deletion is not exposed through the public API.
  • Creating users requires elevated workspace authorization.

Security and key management

  • Set a key expiry when you can. You can choose 30, 90, or 365 days, Never, or a custom date.
  • Rotate keys on a regular schedule and immediately after a suspected leak. Rotation creates a new token and revokes the old one.
  • Revoke a key at any time to stop it immediately.
  • Store keys in a secret manager or protected environment variable. Do not place them in browser code, screenshots, or source control.
  • Each key is limited to its own workspace. It cannot read or write another FyneDesk workspace.

Frequently asked questions

Which plan do I need?

The full REST API and API key creation are available on Business. Outbound webhooks remain available on Pro and Business.

Can I make a key read only?

Yes. Select only read scopes for the resources your integration needs. Write and delete permissions are separate.

How do I rotate a key?

Open Admin Settings → Developer & Data → API Keys. Choose the key and select Rotate. Update your integration with the new token because the old token stops working.

Are API changes audited?

Yes. API activity appears in the same history your team uses to understand who changed what and when, including deletions.

Should I use the API or webhooks?

Use the API to read or change FyneDesk data. Use webhooks when you need a real time notification that something changed. Most connected systems use both.

Next steps

Open Admin Settings → Developer & Data → API Keys to create a scoped key or switch to the built-in API Reference tab. Keep the OpenAPI specification beside your client while implementing. You can also review Webhooks & Integrations and FyneDesk plans.

← Back to Help CenterCreate Free Account