Skip to main content

API Reference

The Daspire Control API is the public management API for automating Daspire setup and operations.

Base URL:

https://api.daspire.com/daspire/api/control/v1

OpenAPI:

https://docs.daspire.com/openapi/daspire-control-v1.yaml

Every successful response includes a request_id and a data object.

{
"request_id": "7a9d7e5f-0fd5-4a6f-92f2-f5f8d50f7f7b",
"data": {}
}

Errors use this shape:

{
"code": "403",
"message": "Permission denied",
"details": {},
"request_id": "7a9d7e5f-0fd5-4a6f-92f2-f5f8d50f7f7b"
}

Core Endpoints​

AreaEndpoints
Current userGET /me
WorkspacesGET /workspaces, GET /workspaces/{workspace_id}/members, POST /workspaces/{workspace_id}/members/invitations, DELETE /workspaces/{workspace_id}/members/{member_id}
ConnectorsGET /connectors, GET /connectors/{connector_id}, GET /connectors/{connector_id}/spec
CredentialsPOST /credentials, GET /credentials/{credential_id}, POST /credentials/clickup/oauth/start, POST /credentials/clickup/oauth/callback, POST /credentials/source/oauth/start, POST /credentials/source/oauth/callback
MailcoachPOST /credentials/mailcoach/api-token, POST /connectors/mailcoach/check, POST /connectors/mailcoach/edm/preview
SourcesPOST /sources, PATCH /sources/{source_id}, DELETE /sources/{source_id}
DestinationsPOST /destinations, PATCH /destinations/{destination_id}
PipelinesPOST /pipelines/prepare, POST /pipelines, PATCH /pipelines/{pipeline_id}, DELETE /connections/{connection_id}, POST /pipelines/{pipeline_id}/pause, POST /pipelines/{pipeline_id}/resume, POST /pipelines/{pipeline_id}/sync
Reverse ETLPOST /reverse-etl/prepare, GET /reverse-etl/models, POST /reverse-etl/models, PATCH /reverse-etl/models/{modelId}, DELETE /reverse-etl/models/{modelId}, GET /reverse-etl/destinations, POST /reverse-etl/destinations, PATCH /reverse-etl/destinations/{destinationId}, DELETE /reverse-etl/destinations/{destinationId}, GET /reverse-etl/activations, POST /reverse-etl/activations, PATCH /reverse-etl/activations/{activationId}, DELETE /reverse-etl/activations/{activationId}, POST /reverse-etl/activations/{activationId}/run, GET /reverse-etl/runs/{runId}
JobsGET /jobs/{job_id}
ApprovalsGET /approvals, GET /approval-policies, PATCH /approval-policies/{category}, POST /approvals/{approval_id}/approve, POST /approvals/{approval_id}/reject
AuditGET /audit-logs, GET /sessions, POST /sessions/{session_id}/revoke

POST /pipelines/{pipeline_id}/sync returns HTTP 409 with code EXECUTION_CONFLICT when a sync/reset is already active or the registered schedule material changed before the command was accepted. Refresh the pipeline status before retrying; a 409 does not authorize submitting a duplicate job.

Source OAuth​

Source connector OAuth flows use the Daspire Control API. The runtime OAuth exchange is handled internally, and the public callback response returns a Daspire credential_handle instead of provider tokens.

EndpointPurpose
POST /credentials/source/oauth/startReturn the provider authorization URL for a source connector.
POST /credentials/source/oauth/callbackStore the OAuth result as a Daspire credential and return a credential_handle.

MCP exposes these through daspire_get_source_oauth_consent_url and daspire_complete_source_oauth.

Mailcoach​

Mailcoach access uses product-owned Control API routes and the product connector id conn_mailcoach_sellersync_edm.

The source catalog also uses conn_mailcoach_sellersync_edm as the primary connector_id for creating the Mailcoach source. The legacy runtime source definition id source:efd2f044-dcbb-52ee-98d0-c169d9d092b9 remains compatibility-only for old saved URLs/configuration.

Use POST /credentials/mailcoach/api-token to store the Mailcoach bearer token and return a Daspire credential_handle. Use that handle with POST /connectors/mailcoach/check or POST /connectors/mailcoach/edm/preview.

Mailcoach supports both self-hosted instances and Mailcoach Cloud. The optional connection_method field defaults to self_hosted; existing configurations without it continue to work. Customers must enter the Mailcoach API base URL explicitly. For self-hosted Mailcoach, enter the customer's own instance API URL ending in /api; for Mailcoach Cloud, use https://[your-domain].mailcoach.app/api.

The Mailcoach base_url must be an approved HTTPS Mailcoach host. Plain HTTP, localhost, private/internal hosts, user-info URLs, query strings, fragments, and non-443 ports are rejected before any provider request is made.

Legacy connector aliases such as source:mailcoach are accepted only for old saved configurations. Default requests use credential_handle; direct raw-token calls are limited to credential creation. Default responses return connector_id, credential_handle, data-source status, field coverage, and sanitized campaign metrics; they do not return provider tokens, raw Mailcoach payloads, runtime ids, Docker image fields, stack traces, or runtime auth metadata.

These endpoints do not create, migrate, delete, or update existing customer sources, connector definitions, selected catalogs, schedules, jobs, billing/usage records, or warehouse naming. Preview responses mark traffic and sales metrics as requiring external attribution joins.

Safety Model​

MCP clients return approval proposals for write operations by default. Workspace administrators can use GET /approval-policies and PATCH /approval-policies/{category} to choose which MCP categories require approval. Requests sent with X-Daspire-Execution-Mode: proposal always return an approval proposal.

Source deletion is guarded: delete associated connections first, then call DELETE /sources/{source_id}. Delete responses include a post-delete verification flag. Connection deletion succeeds only after the platform confirms the connection is deleted. Native connections first stop future scheduling and require no queued or running job; cancel and reconcile any active job before retrying deletion. Historical jobs and retry snapshots are retained, while new execution is blocked. If a response is uncertain, read the connection and approval outcome before retrying.

Secret values are accepted only through secure credential flows and are never returned by the API. API responses use credential_handle when a credential needs to be referenced.

Zoho Social Source​

Zoho Social is exposed through the existing Control API connector and source endpoints. Use connector_id, source_id, and credential_handle as primary fields. Legacy runtime aliases such as source:85124378-057c-4755-b3bb-b9e614a229be are accepted only for saved configuration compatibility.

After OAuth, POST /sources/entities returns customer-safe Zoho Social options for portal_id, brand_ids, and channel_ids. The product UI requires Brand and Channel selection through those provider-backed options; raw IDs remain accepted by the API only for saved-source compatibility. No customer-facing legacy execution-kernel route is added. Runtime access stays behind the existing connector/source gateway projection, and default customer responses do not include provider tokens, OAuth raw config, Docker image fields, internal paths, raw stack traces, or internal auth details.

Adding this source does not migrate customer connections, connector definitions, selected catalogs, schedules, state, billing or usage records, or _daspire_* warehouse naming. Rollback is limited to disabling the new Zoho Social definition or image tag.

Example​

curl -H "Authorization: Bearer $DASPIRE_TOKEN" \
https://api.daspire.com/daspire/api/control/v1/connectors

Native job cancellation accepts the opaque product job_id returned by job history. Direct and approved cancellations use the shared runtime adapter and the existing workspace approval policy. Cancel an active job and verify its terminal state before retrying connection deletion; cancellation does not submit a replacement sync.

Enabled schedules with an unconfirmed destination outcome​

When deployed, nativeScheduleBlocked distinguishes the enabled schedule from current blocking; latestSyncJobStatus retains the actual most recent sync result. The UI uses the existing Broken state and shows Enabled · blocked while an original destination outcome needs confirmation. A recent sync failure alone does not mean that scheduling is blocked. nativePendingDestinationCommit contains the current reason, pending count and original commit/job/attempt IDs, duration start, last reported verification, alert and next action. Historical start times are labelled estimates; a null time/result means not reported, never confirmed uncommitted.

nativeScheduleBlockedOccurrences exposes up to twelve recent real appointments from existing diagnostic logs, with their original occurrenceKey, reason, scheduledFor, observedAt and original commits. These are scheduling decisions, not failed sync jobs, usage or checkpoints. Older retained entries remain on the original job's diagnostic log. The normal log retention still applies.

VERIFICATION_FAILED, VERIFICATION_STALLED and VERIFICATION_NOT_REPORTED require attention. The one-hour attention threshold does not expire commit protection or grant retry/write permission. Unknown outcomes remain protected while automatic verification continues. These status fields provide observations; they never authorize another write. After safe original settlement the current block clears, while appointment history and the real latest failed sync remain. The next natural appointment resumes without resaving or Sync Now; skipped appointments are not batch-replayed.