DaGiftFoundation API

Quick start

Use a sandbox credential first. The base URL for this site is:

1. 1. Register
   Create or sign in to your DaGiftFoundation account.
2. 2. Create an integration
   Choose the scopes and generate a sandbox key in the portal.
3. 3. Call the API
   Replace the placeholders with your key and returned sample plan id.

API_BASE="https://<this-host>/api/v1"
curl -sS "$API_BASE/business-plans" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Accept: application/json"

curl -i -X POST "$API_BASE/business-plans/PLAN_ID/goals" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Origin: https://<this-host>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Review the sample launch plan","priority":"medium"}'

curl -i -X PATCH "$API_BASE/goals/GOAL_ID" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Origin: https://<this-host>" \
  -H "Content-Type: application/json" \
  -d '{"completed":true}'

The POST example includes an Origin header because the platform CSRF guard requires the exact DaGiftFoundation app origin on every mutation. Requests without it or with a third-party Origin receive 403. Use the sandbox key to keep writes isolated.

Authentication

Send the integration credential as an HTTP Bearer token. Sandbox keys begin with dg_sbx_. production keys begin with dg_live_. The full secret is shown once when created or rotated; only a one-way hash is stored.

• Sandbox keys access only synthetic sandbox plans and goals, never production workspace records.
• Production keys require a published integration and an active workspace grant for each plan and scope.
• Credential validity alone does not grant customer data access. Revoking either the key or the workspace grant blocks later requests.

Permission scopes

A workspace owner reviews the developer name, purpose, compatibility, and requested scopes before selecting a plan and approving only the scopes they choose. Callers cannot widen access by supplying another plan id.

Endpoints

All paths below are relative to the displayed /api/v1 base URL. Collection endpoints accept limit (default 50, maximum 100) and cursor (the returned nextCursor) query parameters.

List response example · values are illustrative only

{
  "environment": "SANDBOX",
  "items": [{
    "id": "<plan_id>",
    "title": "Sample business plan",
    "summary": "Synthetic sandbox workspace for API quick-start requests.",
    "executiveSummary": "This record is isolated test data and is not a customer workspace.",
    "targetCustomer": "Sample local service business",
    "customerProblem": "The example team needs a clear plan for its next launch milestone.",
    "solution": "Use goals and next actions to organize the launch work.",
    "revenueModel": "Sample subscription revenue model.",
    "nextMilestone": "Complete the sample launch checklist.",
    "updatedAt": "<ISO-8601 timestamp>"
  }],
  "limit": 50,
  "hasMore": false,
  "nextCursor": null
}

Create-goal response example · values are illustrative only

{
  "environment": "SANDBOX",
  "item": {
    "id": "<goal_id>",
    "businessPlanId": "<plan_id>",
    "title": "Review the sample launch plan",
    "description": "",
    "targetDate": null,
    "priority": "medium",
    "completed": false,
    "createdAt": "<ISO-8601 timestamp>",
    "updatedAt": "<ISO-8601 timestamp>"
  }
}

Errors and rate limits

{
  "error": { "code": "invalid_request", "message": "Goal fields are invalid." },
  "requestId": "<request_id>"
}

Each credential is limited to 60 requests per 60-second fixed window. Successful and failed calls with a recognized active credential are counted; unauthenticated attempts are not charged to a credential. Credential-validated responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-Request-Id. A 401 or an Origin rejection still includes a request id; a 429 also includes Retry-After seconds.

Versions and change guidance

Only v1 is currently supported. Within v1, optional fields and new endpoints are compatible additions; existing fields keep their meaning. A breaking change requires a new major version. Deprecations and migration guidance will be published in the changelog before removal. No v1 end-of-life date is set.

The supported-version response at GET /api/v1 is the live contract. Review the changelog before upgrading.