canonical: https://jentic.com/apis/kobotoolbox.org/kobotoolbox # KoboToolbox Primary API Jentic publishes the only available OpenAPI specification for KoboToolbox Primary API, keeping it validated and agent-ready. KoboToolbox is the open-source survey and data-collection platform widely used by humanitarian, public-health, and research organisations to design forms, collect responses on mobile devices, and analyse the resulting datasets. The v2 API exposes assets - the unifying concept covering deployed projects, draft projects, library questions, blocks, templates, and collections - alongside survey data, permissions, REST service exports, organisation and team management, library content, and detailed access logs. It does not cover the OpenRosa endpoints, which are documented separately. ## For AI agents Manage KoboToolbox projects, deploy and edit forms, pull survey submissions, manage permissions, and export to REST services across the v2 API. ## Scope Does not handle the OpenRosa form-collection protocol, mobile client offline sync, or KoboToolbox account billing - use for v2 asset management, submissions, permissions, and REST service exports only. ## Capabilities - Create and deploy a KoboToolbox project as a v2 asset - Pull survey submissions from a deployed KoboToolbox project - Edit project content, library questions, and reusable blocks - Manage user, team, and organisation permissions on a project - Configure REST service exports that push submissions to external endpoints - Export access logs and submission data for audit or analysis - Inspect storage and submission usage for an organisation ## Use cases ### Humanitarian Field Data Pipeline Run a continuous pipeline from KoboToolbox forms in the field into an analytics warehouse. The /api/v2/assets/{uid_asset}/ family of endpoints exposes the deployed survey and its submissions, while REST service exports push new responses to a downstream URL. Critical for response teams in humanitarian and public-health contexts who collect data offline on mobile devices and need it visible to coordinators within hours. Example prompt: Pull submissions for asset uid 'aBcDef123' updated in the last hour and write them as JSON rows into the analytics staging bucket. ### Research Survey Audit Audit a research project running on KoboToolbox by combining access logs, asset metadata, and submission counts. /api/v2/access-logs/ and /api/v2/asset_usage/ together produce a defensible record of who saw what and when. Useful for principal investigators preparing for IRB review or for organisations that need a paper trail of data handling decisions. Example prompt: Export the last 7 days of access logs via /api/v2/access-logs/export/ and produce a per-user summary of project access events. ### Project Permissions Automation Automate permission grants for new collaborators across many KoboToolbox projects. The /api/v2/assets/{uid_asset}/ permission endpoints add and revoke user access, so an HR-driven onboarding flow can give a new staffer the same project view as their team without a manual click-through. Saves coordinators hours when teams expand. Example prompt: For each new staff member listed in the HR sheet, grant view access to the 5 active project assets they need. ### REST Service Export Setup Configure REST service exports so submissions flow to an external endpoint as soon as enumerators sync from the field. The /api/v2/assets/{uid_asset}/hooks/ endpoint creates the export configuration on a deployed project. This pattern replaces fragile periodic polling with a push-style integration into the team's existing data stack. Example prompt: Create a REST service hook on asset uid 'aBcDef123' that POSTs new submissions to https://example.com/kobo-incoming. ### Agent-Driven Survey Operations via Jentic Have an AI agent answer field-coordinator questions like 'how many submissions came in this morning' or 'who has access to project X' by calling KoboToolbox through Jentic. The agent searches Jentic for the right v2 operation, loads the schema, and executes with the auth token kept in your Jentic One instance. The agent treats the 171-endpoint surface as a discoverable toolkit instead of a docs maze. Example prompt: Through Jentic, search for 'list KoboToolbox projects', load /api/v2/assets/, and return the count of deployed assets. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /api/v2/assets/ | List assets (projects, library content) | | GET | /api/v2/assets/{uid_asset}/ | Retrieve a single asset | | GET | /api/v2/access-logs/ | List access log entries | | GET | /api/v2/access-logs/export/ | Export access logs | | GET | /api/v2/asset_usage/ | Read asset usage and storage data | | GET | /api/v2/asset_subscriptions/ | Manage asset subscriptions | | GET | /api/v2/asset_snapshots/ | List asset snapshots | ## Key resources - **Assets** — Projects, drafts, library questions, blocks, templates, and collections - **Submissions** — Read survey responses collected from deployed projects - **Permissions** — Grant and revoke user access on assets - **Hooks (REST Services)** — Push submissions to external endpoints - **Library Content** — Manage reusable questions, blocks, and templates - **Access Logs** — Audit project access events - **Asset Usage and Snapshots** — Track storage, submission volumes, and asset versioning - **Organisation and Teams** — Manage organisations, teams, and members ## Why Jentic - **Setup:** Wiring KoboToolbox by hand means learning its token or basic auth and handling the kf.kobotoolbox.org/api/v2 host and its errors yourself. Through Jentic you install once, import KoboToolbox from the API Directory, store the credential once, and your agent calls it. - **Permission scoping:** KoboToolbox puts the asset uid in the URL path (/api/v2/assets/{uid_asset}/), so a rule can pin your agent to one asset: it can read that survey asset and its submissions and nothing else. You choose the operations it may call, so permission or export-service changes are not included unless you add them. - **Credential handling:** Your KoboToolbox credential 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. - **Discovery method:** Agents search Jentic by intent such as 'list survey assets' or 'read submissions for an asset', and Jentic returns the matching KoboToolbox operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **SurveyMonkey API** — Commercial survey platform with broad template and analytics tooling - **Typeform API** — Conversational form builder with strong consumer UX - **Airtable API** — Common downstream destination for KoboToolbox submissions exported via REST hooks ## FAQ ### Why is there no official OpenAPI spec for KoboToolbox API? KoboToolbox does not publish an OpenAPI specification - only a Sphinx-rendered narrative reference. Jentic generates and maintains this spec so that AI agents and developers can call KoboToolbox Primary API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the KoboToolbox API use? The KoboToolbox v2 API supports HTTP Basic auth and Token authentication. The token is sent in the Authorization header. Through Jentic, the token is held in your Jentic One instance and injected at execution time so the agent never sees the raw value. ### Can I pull survey submissions through the KoboToolbox API? Yes. The v2 API treats deployed projects as assets, so submissions are read through the /api/v2/assets/{uid_asset}/ family. For continuous flow rather than polling, configure a REST service hook on the asset to push new submissions to an external endpoint. ### What are the rate limits for the KoboToolbox API? KoboToolbox enforces server-level throttling that varies by deployment (the public kf.kobotoolbox.org instance has tighter limits than self-hosted ones). The spec does not declare a hard number - back off on 429 responses and prefer hooks over tight polling. ### How do I list my projects from an AI agent through Jentic? Search Jentic for 'list KoboToolbox projects', load GET /api/v2/assets/, and execute. Jentic injects the auth token from the vault and the agent receives the asset list including project uid, name, and deployment status. ### Does the v2 API cover OpenRosa endpoints? No. The OpenRosa protocol endpoints used by Collect-style mobile clients are documented separately and are not part of this v2 surface. This spec covers the management, library, and submission-export endpoints under /api/v2/. ### Can I limit what my agent is allowed to do with the KoboToolbox API? Yes. Because you run Jentic One yourself and set the rules, you decide exactly which KoboToolbox operations and credentials your agent may use. Since the asset uid sits in the URL path (/api/v2/assets/{uid_asset}/), you can pin the agent to a single survey asset so it reads only that project and its submissions and nothing else. You also choose the operations it may call, so permission grants and REST export-service changes stay out of reach unless you explicitly add them.