Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.pickfu.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

All API requests should be made to: 
https://api.pickfu.com/v1

​
Authentication

All endpoints require a Bearer token in the Authorization header — either an API key or an OAuth access token: 
Authorization: Bearer sk_your_api_key_here
Create an API key at Settings > API Keys, or use OAuth for interactive apps. See the Authentication guide for details.

​
Request Format

  • All request bodies must be JSON
  • Set the Content-Type: application/json header for POST/PUT/PATCH requests
  • All responses are returned as JSON

​
Response Format

Successful responses include the requested data: 
{
  "id": "abc123-def456",
  "name": "My Survey",
  "status": "completed"
}

​
Error Handling

Error responses include an error type and human-readable message: 
{
  "error": "Not Found",
  "message": "Survey not found"
}

​
HTTP Status Codes

Status CodeDescription
200Success
201Created - resource successfully created
400Bad Request - invalid request body or parameters
401Unauthorized - missing or invalid access token
403Forbidden - insufficient permissions
404Not Found - resource doesn’t exist
429Too Many Requests - rate limit exceeded
500Internal Server Error - something went wrong on our end

​
Validation Errors

When request validation fails, the response includes details about what went wrong: 
{
  "error": "Bad Request",
  "message": "Validation failed",
  "details": [
    "question is required",
    "options must have at least 2 items"
  ]
}

​
Rate Limits

API requests are rate-limited to 100 requests per minute per access token. When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please wait before making more requests."
}
Implement exponential backoff in your application to handle rate limiting gracefully.

​
Pagination

Endpoints that return lists support pagination using page and limit query parameters: 
GET /v1/surveys?page=1&limit=20
Paginated responses include metadata: 
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

​
Available Endpoints

Surveys

Create, retrieve, publish, and manage surveys.

Responses

Read responses, send follow-up questions, and rate or pin responses.

Tags

Organize surveys with tags.

Projects

Group related surveys into projects.

Traits

Audience targeting and reporting demographics.

Media

Generate images from prompts and upload media to the CDN.

Playbooks

Step-by-step research guides.
Explore the endpoints in the sidebar to see detailed documentation for each operation.

​
Building surveys programmatically

Don’t add a separate “explain your reasoning” question. Every PickFu response already includes a required written explanation — respondents have to type why they picked, ranked, or rated something before they can submit. When you POST /surveys, just write your real question (e.g. “Which product image makes you more likely to click?”) and the qualitative explanation field comes back on the response automatically. Adding a second question to capture reasoning duplicates data and, in multi-question surveys, costs an extra question slot.Screen-recording surveys are the one exception — the recording itself is the answer, and the spoken response is returned as mediaTranscription rather than explanation. For every other question type the explanation field is populated on each response.
The built-in explanation lives on each response object returned by GET /surveys/{id}/responses as the explanation field. If you need to dig deeper on a specific respondent’s answer after the survey completes, use POST /surveys/{id}/responses/{responseId}/followup to send them a follow-up question through their PickFu inbox.