Propuls API — Developer Documentation

1. Access by plan

👑 BUSINESS — Read-only

• GET prospects, proposals, quotes/invoices, stats
• 100 requests/hour
• Any POST / PATCH / DELETE request returns 403

💎 PLATINUM — Read + Write

• Everything in Business + create / update / delete
• Prospects, proposals, quotes/invoices, AI, bookings
• 500 requests/hour

2. Authentication

Every request must include a Bearer token in the Authorization.

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects

Generate your key from Settings → API keys.

3. Endpoints

GET/prospectsBusiness + Platinum

List prospects (filters: status, country, limit, offset).

cURL example

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects?limit=50

GET/prospects/{id}Business + Platinum

Prospect details.

cURL example

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

GET/prospects/{id}/proposalsBusiness + Platinum

Commercial offers for a prospect.

cURL example

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

GET/documentsBusiness + Platinum

List quotes/invoices (filters: type, status).

cURL example

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/documents?type=invoice&status=paid

GET/statsBusiness + Platinum

Statistics (period=month|quarter|year).

cURL example

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/stats?period=month

POST/prospectsPlatinum only

Create a prospect. Platinum plan only.

Body

{ "name": "Jane Doe", "company": "Acme", "email": "jane@acme.io", "budget": 5000, "currency": "EUR" }

cURL example

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","company":"Acme"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects

PATCH/prospects/{id}Platinum only

Update a prospect. Platinum plan only.

Body

{ "status": "won", "budget": 8000 }

cURL example

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"won"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

DELETE/prospects/{id}Platinum only

Delete a prospect. Platinum plan only.

cURL example

curl -X DELETE -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

POST/prospects/{id}/proposalsPlatinum only

Create an offer. Platinum plan only.

Body

{ "title": "Refonte site", "amount": 3500, "currency": "EUR" }

cURL example

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"title":"Refonte"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

PATCH/proposals/{id}Platinum only

Update an offer. Platinum plan only.

Body

{ "status": "sent" }

cURL example

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"sent"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/proposals/ID

POST/prospects/{id}/documentsPlatinum only

Create a quote or an invoice. Platinum plan only.

Body

{ "type": "invoice", "amount": 2500, "currency": "EUR" }

cURL example

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"type":"invoice","amount":2500}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/documents

POST/emails/generatePlatinum only

Generate a personalised AI email. Platinum plan only.

Body

{ "prospect_id": "...", "template": "first_contact" }

cURL example

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/emails/generate

POST/whatsapp/generatePlatinum only

Generate an AI WhatsApp message. Platinum plan only.

Body

{ "prospect_id": "...", "template": "relance douce" }

cURL example

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/whatsapp/generate

4. cURL examples by plan

Pick the section matching your plan. Write requests made with a Business key return a 403 plan_forbidden_write.

👑 BUSINESS

Business examples (read-only)

GET/prospects

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects?limit=50

GET/prospects/{id}

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

GET/prospects/{id}/proposals

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

GET/documents

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/documents?type=invoice&status=paid

GET/stats

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/stats?period=month

💎 PLATINUM

Platinum examples (read + write)

GET/prospects

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects?limit=50

GET/prospects/{id}

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

GET/prospects/{id}/proposals

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

GET/documents

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/documents?type=invoice&status=paid

GET/stats

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/stats?period=month

POST/prospects

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","company":"Acme"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects

PATCH/prospects/{id}

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"won"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

DELETE/prospects/{id}

curl -X DELETE -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

POST/prospects/{id}/proposals

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"title":"Refonte"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

PATCH/proposals/{id}

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"sent"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/proposals/ID

POST/prospects/{id}/documents

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"type":"invoice","amount":2500}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/documents

POST/emails/generate

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/emails/generate

POST/whatsapp/generate

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/whatsapp/generate

5. Code examples

Python

import requests
r = requests.get(
  "https://propulse-ton-freelance.lovable.app/api/public/v1/prospects",
  headers={"Authorization": "Bearer sk_live_xxx"}
)
print(r.json())

JavaScript

const r = await fetch(
  "https://propulse-ton-freelance.lovable.app/api/public/v1/prospects",
  { headers: { Authorization: "Bearer sk_live_xxx" } }
);
console.log(await r.json());

6. Error codes & actionable messages

Every error returns a structured JSON payload: { error, code, upgrade_url?, docs_url?, retry_after_seconds?, limit_per_hour? }. code — to display a translated message and offer the matching action to the user.

HTTP	code	Meaning & recommended action
401	invalid_key	Invalid or revoked API key. Generate a new key in Settings → API keys.
403	plan_no_api_access	The plan does not include API access. Suggested message: “This action requires a Business or Platinum plan — upgrade your plan ».
403	plan_forbidden_write	Write request (POST/PATCH/DELETE) from a Business key. Suggested message: “This action requires the Platinum plan — upgrade ». The action URL is provided in `upgrade_url`.
400	—	Missing or invalid field. Fix the payload.
404	—	Resource not found.
429	rate_limited	Hourly quota reached (100/h Business · 500/h Platinum). The body includes `retry_after_seconds` & `limit_per_hour`. Suggested message: “Rate limit reached, retry in X minutes — see rate limits ». The HTTP header `Retry-After`.
500	internal_error	Temporary server error. Retry or contact support.

403 example (Business POST):

{
  "error": "This action requires the Platinum plan. Business API keys are read-only.",
  "code": "plan_forbidden_write",
  "upgrade_url": "https://propulse-ton-freelance.lovable.app/app/upgrade",
  "docs_url": "https://propulse-ton-freelance.lovable.app/docs/api"
}

429 example:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": "Rate limit exceeded (100/hour). Retry in a few minutes.",
  "code": "rate_limited",
  "retry_after_seconds": 3600,
  "limit_per_hour": 100,
  "docs_url": "https://propulse-ton-freelance.lovable.app/docs/api#rate-limits"
}

7. Per-endpoint limits (detailed rate limits)

All v1 requests share the same hourly counter per account (internal endpoint api_v1): 100 req/h on Business, 500 req/h on Platinum. The counter is decremented by every authenticated request, whatever the verb.

Method	Endpoints	Business (read-only)	Platinum
GET	/prospects, /prospects/:id, /prospects/:id/proposals, /prospects/:id/documents, /proposals/:id, /documents, /stats	✅ 100 req/h	✅ 500 req/h
POST	/prospects, /prospects/:id/proposals, /prospects/:id/documents, /emails/generate, /whatsapp/generate	❌ 403 `plan_forbidden_write`	✅ 500 req/h
PATCH	/prospects/:id, /proposals/:id	❌ 403 `plan_forbidden_write`	✅ 500 req/h
DELETE	/prospects/:id	❌ 403 `plan_forbidden_write`	✅ 500 req/h

429 example — read quota exceeded (GET):

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": "Rate limit exceeded (100/hour). Retry in a few minutes.",
  "code": "rate_limited",
  "retry_after_seconds": 3600,
  "limit_per_hour": 100,
  "docs_url": ".../docs/api#rate-limits"
}

403 example — write from a Business key:

HTTP/1.1 403 Forbidden

{
  "error": "This action requires the Platinum plan. Business API keys are read-only.",
  "code": "plan_forbidden_write",
  "upgrade_url": ".../app/upgrade",
  "docs_url": ".../docs/api"
}

Best practices:

Honour the Retry-After header instead of retrying immediately.
Apply exponential backoff (2s → 4s → 8s → …) on 429 and 500 errors.
Batch reads: prefer one GET /prospects?limit=100 over 100 GET /prospects/:id.
Cache GET /stats responses client-side.