Official vendor OpenAPI document · agent-readyProductivityForms Surveysbearer42 EndpointsREST
For Agents
Create, target, and publish PickFu consumer polls such as head-to-head and ranked questions, then read responses, AI summaries, click-test heatmaps, price sensitivity results, and CSV exports.
Use for: Create a head-to-head poll comparing two book cover designs, Publish my draft survey to US women aged 25 to 34, Get the AI summary and results for a completed survey, List all surveys that are still in progress
Not supported: Does not send surveys to your own customer list, host embedded web forms, or run email campaigns. Use for consumer panel polls and their results only.
The PickFu API creates consumer polls, targets them at a respondent panel by demographic traits, and returns the answers. A survey holds questions of types such as head_to_head, ranked, open_ended, click_test, and van_westendorp, is created as a draft, and is published to start collecting responses, then stopped or extended with more respondents. Results come back as individual responses with written explanations and demographic traits, AI-generated summaries, click-test heatmaps and click regions, Van Westendorp price curves, and CSV, PDF, and PNG exports, alongside templates, playbooks, projects, tags, and AI image generation for poll options.
Install Jentic One Beta
Connect the PickFu API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the PickFu API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fpickfu.com%2Fpickfu" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fpickfu.com%2Fpickfu" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with PickFu API.
Draft a survey with head_to_head, ranked, open_ended, click_test, or van_westendorp questions and a sampleSize
Target respondents by demographic traits per country and choose reporting breakdowns
Publish a draft survey to the panel, stop a live one, or extend a completed one with more respondents
Read individual responses filtered by question_id, explanation text, or respondent traits
Get click-test heatmaps and click-region counts, and Van Westendorp price sensitivity curves
Search completed surveys semantically and export results as CSV, PDF, or PNG
Generate an AI image from a prompt or upload media to use as poll options
Use Cases
Patterns agents use PickFu API for, with concrete tasks.
★ Design-testing agent through Jentic
An AI agent helping a seller choose between product images can run a real consumer poll instead of guessing. Through Jentic the agent searches for 'create a consumer poll', loads the PickFu createSurvey operation with its input schema, drafts a head_to_head question with both images and targeting traits, publishes it, and later reads the responses and AI summary. The bearer token is injected at call time by your own Jentic One instance, and publishing deducts credits from your PickFu account.
Call POST /surveys with a head_to_head question for two uploaded images, country US, and sampleSize 50, then call POST /surveys/{id}/publish and later GET /surveys/{id} for the results and summary
Audience-segmented feedback analysis
Product teams want to know not just which option won but who preferred it and why. Survey responses include the respondent's answer, written explanation, and demographic traits, and can be filtered by trait permalinks such as male or age-25-34, by question_id, or by keyword in the explanation. Pinning and rating responses keeps the most useful comments easy to find.
Call GET /surveys/{id}/responses with traits 'female,age-25-34' and text 'price', then call PUT /surveys/{id}/responses/{responseId}/pin with pinned true on the clearest comment
Click tests and price sensitivity
Click-test questions show where respondents click on an image, such as a landing page or app store listing. PickFu returns a rendered heatmap PNG and named click regions with first-click or all-click counts. For pricing research, van_westendorp questions return the four cumulative price curves and the named price intersections PMC, OPP, IPP, and PME.
Call GET /surveys/{id}/questions/{questionId}/van-westendorp for a completed pricing question and report the optimal price point and acceptable price range
Research repository search and export
Teams that have run many polls can query their own history. Semantic search over completed surveys takes a natural-language query and returns matching results for the team, and the exports operation returns download URLs for CSV results, PDF reports, and PNG screenshots, with the CSV stream available in v1 or v2 format.
Call POST /semantic-search/search with query 'packaging colour preferences', then GET /surveys/{id}/exports for the best match and return its CSV and PDF links
Key Endpoints
42 endpoints — the pickfu api creates consumer polls, targets them at a respondent panel by demographic traits, and returns the answers.
METHOD
PATH
DESCRIPTION
POST
/surveys
Create a draft survey
POST
/surveys/{id}/publish
Publish a draft survey
GET
/surveys/{id}
Get a survey with results and summaries
GET
/surveys/{id}/responses
List individual responses
GET
/traits/targeting
List audience targeting traits
GET
/surveys/{id}/questions/{questionId}/heatmap
Get a click-test heatmap
POST
/semantic-search/search
Search completed surveys semantically
GET
/surveys/{id}/exports
Get survey export links
POST
/surveys
Create a draft survey
POST
/surveys/{id}/publish
Publish a draft survey
GET
/surveys/{id}
Get a survey with results and summaries
GET
/surveys/{id}/responses
List individual responses
GET
/traits/targeting
List audience targeting traits
GET
/surveys/{id}/questions/{questionId}/heatmap
Get a click-test heatmap
POST
/semantic-search/search
Search completed surveys semantically
GET
/surveys/{id}/exports
Get survey export links
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
P
PickFu API
- AI-Aware (B-)62/100
56
Foundational Compliance61
Developer Experience & Jentic Compatibility47
AI-Readiness & Agent Experience94
Agent Usability75
Security75
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.2
Show dimension breakdown
56
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: CSignals: 4
92%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
0%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
30%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
61
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: B-Signals: 4
0%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
45%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
47
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: DSignals: 4
51%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
88%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
49%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
75
Security
Trust, risk posture, and security compliance.
Grade: A-Signals: 1
75%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
75
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: A-Signals: 1
75%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring PickFu by hand means creating an API key or running its OAuth 2.0 flow, sending the bearer token, choosing between the production and sandbox hosts, and polling surveys until responses arrive. Through Jentic you install once, import PickFu from the API Directory, store the token once, and your agent calls it.
Permission scoping
PickFu puts the survey id in the URL path (/surveys/{id}/publish, /surveys/{id}/responses), so a rule can pin your agent to one survey and the operations you pick. You choose the operations it may call, so credit-spending or destructive ones like publishing, adding respondents, or deleting a survey are not included unless you add them.
Credential isolation
Your PickFu token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'create a consumer poll' or 'get survey responses by demographic', and Jentic returns the matching PickFu operation with its input schema, including question types and targeting traits, so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using PickFu API through Jentic.
What authentication does the PickFu API use?
The PickFu API authenticates with an HTTP bearer token (bearerAuth) per its OpenAPI spec: either a PickFu API key or an OAuth 2.0 access token, sent as 'Authorization: Bearer'. The CSV export stream also accepts a short-lived signed token in its t query parameter, issued by the survey exports operation. Through Jentic the token is stored by your own instance and attached at call time.
Does publishing a survey with the PickFu API cost money?
Yes. Per the spec, POST /surveys/{id}/publish requires sufficient credits on the account, and credits are deducted when the survey is published. Only draft surveys can be published, and a survey needs at least one question with options. Stopping a live survey with POST /surveys/{id}/stop is irreversible.
What are the rate limits for the PickFu API?
Per the OpenAPI spec, only selected endpoints enforce per-caller rate limits, currently the CSV export endpoints, which return 429 Too Many Requests when exceeded. The CSV export at GET /surveys/{id}/exports/csv is limited to 10 requests per minute per caller. See the PickFu developer docs at https://www.pickfu.com/docs/developers/authentication and each endpoint description for current budgets.
Is there a PickFu MCP server?
You don't need an MCP server to give your agent PickFu. Jentic connects it directly from the API Directory: import it, store your key once, and your agent calls the survey and response operations on demand without loading another server's tool definitions into its context.
How do I run a poll through Jentic?
Search Jentic for 'create a consumer poll', load the POST /surveys operation, and execute it with a name, a question such as head_to_head with two options, targeting traits, and a sampleSize. Then call the publish operation and read results with GET /surveys/{id}. To run it on your own infrastructure, install Jentic One from its GitHub repo.
Can I limit what my agent is allowed to do with the PickFu API?
Yes. Write a rule that allows POST /surveys and PATCH /surveys/{id} but not the publish operation, and the agent can draft polls for your review without spending credits, while you publish them yourself. Every call it makes is logged for review.
GET STARTED