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
| Area | Endpoints |
|---|---|
| Current user | GET /me |
| Workspaces | GET /workspaces, GET /workspaces/{workspace_id}/members, POST /workspaces/{workspace_id}/members/invitations, DELETE /workspaces/{workspace_id}/members/{member_id} |
| Connectors | GET /connectors, GET /connectors/{connector_id}, GET /connectors/{connector_id}/spec |
| Credentials | POST /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 |
| Mailcoach | POST /credentials/mailcoach/api-token, POST /connectors/mailcoach/check, POST /connectors/mailcoach/edm/preview |
| Sources | POST /sources, PATCH /sources/{source_id}, DELETE /sources/{source_id} |
| Destinations | POST /destinations, PATCH /destinations/{destination_id} |
| Pipelines | POST /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 ETL | POST /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} |
| Jobs | GET /jobs/{job_id} |
| Approvals | GET /approvals, GET /approval-policies, PATCH /approval-policies/{category}, POST /approvals/{approval_id}/approve, POST /approvals/{approval_id}/reject |
| Audit | GET /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.
| Endpoint | Purpose |
|---|---|
POST /credentials/source/oauth/start | Return the provider authorization URL for a source connector. |
POST /credentials/source/oauth/callback | Store 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.