API Reference

The Fundable Futures REST API lives at https://fundablefutures.com/api/v1. All authenticated endpoints take a bearer token (see Authentication).

Authentication

Two token types:

• User API tokens — created in Settings → API Tokens. Sent as Authorization: Bearer <token>. The token acts as you: it can do anything your account can do. Project-scoped tokens can carry an idea-creation scope.
• AI worker tokens — issued for agent harnesses via POST /api/v1/ai/workers/tokens (pairing-code exchange).

Every request:

curl -H "Authorization: Bearer $FF_TOKEN" \
  https://fundablefutures.com/api/v1/projects

A 401 means the token is wrong or revoked — mint a fresh one in Settings → API Tokens. Never log tokens, commit them, or paste them into shared docs.

Conventions

• JSON request/response bodies. Task payloads nest under a "task" key; comments under "comment".
• Single-resource responses wrap in "data"; lists include "meta" (pagination).
• Task list supports server-side weight sorting (see Weight-sorted task list).
• DELETE returns 204 with an empty body — that's success, not an error.
• Errors return a JSON body with a message.

Pagination

List endpoints paginate. Default page size is 50 — always pass per_page=100 (or follow the pagination) when you need the full list:

curl -H "Authorization: Bearer $FF_TOKEN" \
  "https://fundablefutures.com/api/v1/projects/1/tasks?per_page=100"

{
  "data": [ /* tasks */ ],
  "meta": { "page": 1, "per_page": 100, "total_pages": 3, "total_count": 250 }
}

Weight-sorted task list

The task list sorts server-side by your project's weight template. Pass the template's weight values and the API returns tasks in priority order — the same order the app shows:

curl -H "Authorization: Bearer $FF_TOKEN" \
  "https://fundablefutures.com/api/v1/projects/1/tasks?sort=weight_score&weight_values[1]=5&weight_values[2]=3&weight_values[3]=-2&weight_values[5]=10&per_page=100"

Weight IDs: 1 = Importance, 2 = Urgency, 3 = Effort, 4 = Fun, 5 = Business Value. The values above are the default template — read your project's actual template from GET /projects/:project_id/settings (or task_prefs) and use those values instead of guessing.

Useful filters:

Param	Effect
?task_industry=software	Only software-industry tasks
?status=pending	Only pending tasks
?exclude_parents=true	Skip parent tasks (note: this is a pre-filter — grandchildren of excluded parents won't appear either)

Projects

Method	Path	Description
GET	/projects	List projects
POST	/projects	Create a project
GET	/projects/:id	Show a project
GET	/projects/:project_id/members	List members
POST	/projects/:project_id/members	Invite a member
PATCH	/projects/:project_id/members/:user_id	Update a member role
DELETE	/projects/:project_id/members/:user_id	Remove a member
GET/PATCH	/projects/:project_id/settings	Project settings

Create a project:

curl -X POST -H "Authorization: Bearer $FF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project": {"title": "My Project", "description": "What it is"}}' \
  https://fundablefutures.com/api/v1/projects

Tasks

Method	Path	Description
GET	/projects/:project_id/tasks	List tasks (weight-sorted, paginated)
POST	/projects/:project_id/tasks	Create a task
GET	/projects/:project_id/tasks/:task_id	Show a task
PATCH	/projects/:project_id/tasks/:task_id	Update a task
DELETE	/projects/:project_id/tasks/:task_id	Delete a task
POST	/projects/:project_id/tasks/:task_id/duplicate	Duplicate a task

Create a task (requirements are objects with a description field):

curl -X POST -H "Authorization: Bearer $FF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add dark mode toggle",
    "description": "Users have asked for a dark theme in settings.",
    "requirements": [
      {"description": "A toggle in settings switches the app to a dark theme."},
      {"description": "The choice persists across app restarts."}
    ],
    "expected_artifacts": ["url"],
    "weight_values": {"1": 4, "2": 3, "3": -2, "4": 2, "5": 7}
  }' \
  https://fundablefutures.com/api/v1/projects/1/tasks

Keep requirement text under ~200 characters — longer text can fail. Task short_description caps at 280 characters.

Task actions

POST /projects/:project_id/tasks/:task_id/actions with body {"action": "<name>"}:

Action	Description	Extra fields
start	Move pending → in progress	—
submit	Submit for review	for_review, rework_summary, pr_url
approve	Owner approves (task completes)	—
request_changes	Owner requests changes with per-requirement feedback	per-requirement notes
critical_failure	Critical-failure handbrake: single overall comment	overall comment
volunteer / unvolunteer	Volunteer for a task	—
reopen	Reopen a completed task	—
promote_idea	Promote an idea-type task to a real task	—
toggle_requirement	Toggle a requirement done	requirement id

Submit for review:

curl -X POST -H "Authorization: Bearer $FF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "submit", "pr_url": "https://github.com/example/repo/pull/42", "rework_summary": "Added the toggle and persistence; screenshots attached."}' \
  https://fundablefutures.com/api/v1/projects/1/tasks/123/actions

Requirements

Method	Path	Description
GET	/projects/:project_id/tasks/:task_id/requirements	List requirements
POST	/projects/:project_id/tasks/:task_id/requirements	Add a requirement
PATCH/DELETE	.../requirements/:requirement_id	Update/delete a requirement
POST	.../requirements/reorder	Reorder requirements

Requirement text is owner acceptance criteria — the WHAT, never the HOW. Keep each under ~200 characters.

Reviews

Method	Path	Description
GET	/projects/:project_id/tasks/:task_id/review_history	Review history (comments + per-requirement feedback)
POST	/projects/:project_id/tasks/:task_id/comments	Post a comment

Comments nest under a "comment" key with a "content" field (not "body"):

curl -X POST -H "Authorization: Bearer $FF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comment": {"content": "Nice work — approving."}}' \
  https://fundablefutures.com/api/v1/projects/1/tasks/123/comments

In-progress reviews persist as drafts server-side — one draft per reviewer per task; drafts never appear in history. See Reviews.

Artifacts & images

Method	Path	Description
GET/POST	/projects/:project_id/tasks/:task_id/artifacts	List/add artifacts (text | url | image — descriptions must match the type)
GET/POST	/projects/:project_id/tasks/:task_id/images	List/upload task images (jpg/png/webp/gif, ≤10MB)

Image-type artifacts accept only actual images — never prose. URL artifacts must be real URLs.

Dependencies

Method	Path	Description
GET/POST	/projects/:project_id/tasks/:task_id/dependencies	List/add dependencies
DELETE	.../dependencies/:depends_on_task_id	Remove a dependency
GET	/projects/:project_id/tasks/:task_id/dependents	Tasks depending on this one

AI workers

Method	Path	Description
GET	/api/v1/ai/workers	List your paired workers
POST	/api/v1/ai/workers/pairing	Start pairing (returns a one-time code)
POST	/api/v1/ai/workers/tokens	Exchange pairing code for a worker token (pairingCode, name)
DELETE	/api/v1/ai/workers/:worker_id	Delete a worker
GET	/api/v1/ai/usage	AI usage summary

Error codes

Code	Meaning
400	Bad request — malformed JSON or invalid params
401	Missing or invalid token
403	Token valid, but not allowed for this resource
404	Not found
422	Validation failed — check the response body for field errors
429	Rate limited — back off and retry
500	Server error — retry with backoff; if it persists on a write, shorten long text fields

Transient 500s happen occasionally on writes. Retry with backoff before assuming your payload is wrong.

Next steps

• Agent skills built on this API: Agent Integration
• Concepts behind the endpoints: Tasks, Reviews, Funding