Source: https://conversionlab.app/docs/ai/agent # Use the Agent with your project work Ask questions, inspect sources, and review proposed ideas, insights, and experiments. The **Agent** is an AI-assisted experience for working with team context. It is available when the product offers it, your team has not opted out, and the account's access and AI usage limits allow it. ## Start a conversation 1. Choose the intended team and project context. 2. Open **Agent** or an AI entry point on the item you are reviewing. 3. Ask a question that names the work or outcome you care about. 4. Inspect the response, referenced entities, and visible tool activity. 5. Open linked work to verify important claims against the source records. For example: “Which observations support our checkout ideas?” is more focused than “What should we test?” Include the relevant project or item when several have similar names. ## Review proposed records The Agent can present proposals for ideas, insights, and experiments. A proposal card lets you inspect the name, description, project, and related fields before creating the item. Edit inaccurate wording or relationships, then choose the create action. Discard proposals you do not want to turn into work. A proposed record is not saved merely because text describing it appears in chat. Confirm the card's created state and open the resulting item after accepting it. Creation still respects your role and plan limits. ## Return to a conversation Use the Agent's conversation list to reopen your own threads. AI Conversations belong to the individual user within a team and are private by default; they are not a shared team chat history. Use response feedback controls when an answer is helpful or problematic. If a response is incomplete or a tool fails, preserve the specific error and retry a focused request after checking the source work. If Agent disappears, check [AI availability and privacy](https://conversionlab.app/docs/ai/privacy). The core research and experiment workflows remain available according to the team's ordinary access. --- Source: https://conversionlab.app/docs/ai/audits # Run and review a pricing page audit Capture a page and inspect AI-assisted findings in their original context. Audits provide an AI-assisted review of a pricing page. The Audits area is optional and depends on product and team availability. Select the project before starting. ## Run an audit 1. Open **Research → Audits** and choose **Run audit**. 2. Enter the pricing page URL. 3. Add useful context, such as the target segment, competitors, constraints, or a specific pricing concern. 4. Start the audit and open its detail page to follow progress. Use a page that can be reached by the capture service. A login wall, unavailable URL, or blocked capture can prevent the audit from completing or produce incomplete context. ## Review the output Inspect the summary, the evaluated lenses, and the findings shown on the page. Review observations, insights, and suggested ideas where present, then compare them with the **Desktop** and **Mobile** captures. AI findings are interpretations of the captured material. Check whether the capture represents the intended page state and whether each finding is supported before turning it into an experiment or reusable learning. Follow connected research records to refine their wording and evidence. Keep useful audit evidence in the same project as the work it informs. ## Recover a failed audit Read the displayed status and error, confirm the URL is reachable, and verify the team still has AI access before trying again. Avoid starting multiple copies while an audit is already running. If the section is absent, use ordinary [observations](https://conversionlab.app/docs/research/observations) and ask an owner or admin about availability. --- Source: https://conversionlab.app/docs/ai/daily-briefs # Read and discuss today’s brief Use the daily briefing as a starting point for reviewing current work. When a daily brief is available, the dashboard shows **Today's brief** with its date and a short indication of the content. ## Review the brief 1. Select the intended team. 2. Open **Explore brief**. 3. Read the takeaways in **Morning briefing**. 4. Follow the context into the relevant project work before acting on a recommendation. 5. Choose **Discuss this with the agent** to open a conversation seeded with the brief. Opening the brief records it as viewed. A brief is a generated summary of available context, so use it to identify what to inspect rather than as a substitute for the underlying record or result report. ## If no brief appears The banner is shown only when a brief exists. Its absence does not mean your team has no activity. Check [AI availability](https://conversionlab.app/docs/ai/privacy), the team you selected, and the normal Research, Ideas, and Experiments areas. External tools can read today's available brief using the supported REST operation or MCP tool; those read interfaces do not generate a new brief. See the [developer reference](https://conversionlab.app/docs/developer). --- Source: https://conversionlab.app/docs/ai # AI-assisted experiences Use the Agent and generated context with deliberate review and team privacy controls. ## Choose a task [Use the Agent with your project work](https://conversionlab.app/docs/ai/agent) Ask questions, inspect sources, and review proposed ideas, insights, and experiments. [Read and discuss today’s brief](https://conversionlab.app/docs/ai/daily-briefs) Use the daily briefing as a starting point for reviewing current work. [Run and review a pricing page audit](https://conversionlab.app/docs/ai/audits) Capture a page and inspect AI-assisted findings in their original context. [Manage AI availability and retained artifacts](https://conversionlab.app/docs/ai/privacy) Control Team AI Opt-Out and explicitly delete or rebuild retained AI context. --- Source: https://conversionlab.app/docs/ai/privacy # Manage AI availability and retained artifacts Control Team AI Opt-Out and explicitly delete or rebuild retained AI context. Owners and admins manage **Settings → Organization → AI**. The page distinguishes **Platform AI Availability**, the team's **Team AI Opt-Out** choice, and the effective availability shown for the team. Billing access and AI usage limits can also affect whether an experience is usable. ## Prevent AI use of team data Enable **Prevent AI use of team data** under Team AI Opt-Out, then save. The choice stops AI entry points, chat access, background AI jobs, and context indexing for that team. Owners and admins can change the choice later. Opting out does not delete already retained AI Conversations or the **AI Context Index**. Deletion requires one of the explicit purge actions. ![AI settings for Acorn Outfitters with Team AI Opt-Out enabled, effective AI availability, and separate controls for retained artifacts.](https://conversionlab.app/docs/images/workflows/ai-settings.webp) ## Review and purge retained artifacts The retained-artifact section shows summaries, not other users' conversation contents. Choose the appropriate action: - **AI Context Index:** deletes retained searchable AI context for the team; source records remain intact. - **Team AI Conversations:** deletes every stored AI Conversation for that team, including private conversations owned by teammates. - **My AI Conversations:** deletes only your own stored AI Conversations in that team. Read the confirmation before purging. These deletion actions are permanent and scoped to the current team; they do not delete conversations in your other teams. ## Rebuild the context index When available, use the rebuild action to refresh searchable AI context from source records. Review the estimate and confirmation before queueing it. The page shows queued, running, completed, failed, or cancelled status. While a rebuild is queued or running, existing retained context may still be retrieved. Do not treat a queued rebuild as completed. If it fails, inspect the reported error before requesting another rebuild. ## Understand provider processing ConversionLab's AI-assisted experiences may send the relevant request and source context to these providers: | Provider | Purpose | | --------- | -------------------------------------------------------------------------------------------------------- | | Anthropic | Agent conversations, insight drafting, pricing page audit analysis, and daily briefs. | | OpenAI | Agent conversations, insight drafting, and pricing page audit analysis when used for those experiences. | | Jina AI | Creating the AI Context Index and representing search queries so relevant team content can be retrieved. | The data needed depends on the action. A conversation can include your messages and retrieved work context; an insight draft uses selected observations; an audit uses captured page content and supplied context. Context indexing processes text from supported team records, and context search processes the search query. These provider purposes describe the shipped experiences. Do not infer provider training or retention commitments merely from a feature being called private. AI Conversations are private between users by default, which is separate from how a provider processes a request. Read the [Privacy Policy](https://conversionlab.app/privacy-policy) for the service's broader privacy information. External AI clients connected through [MCP](https://conversionlab.app/docs/developer/mcp-setup) also have their own client configuration and data handling. Review the client you authorize and use a token with the intended abilities. --- Source: https://conversionlab.app/docs/concepts/collaboration # Collaborate with comments, attachments, and activity Keep discussion and evidence next to the work they describe. Ideas, insights, and experiments offer a shared detail view for their context. Attach the supporting material and keep discussion beside the relevant item. ## Add supporting images Open the item's **Attachments** section and drag in an image or use the upload picker. Use JPEG, PNG, or GIF images up to 5 MB for the browser uploader, with up to ten images on the item. Wait for the upload to complete and check that the image appears on the intended record. Select an image to enlarge it for inspection. An image attached to one item does not automatically become a research conclusion; explain its relevance in the description or link supporting research. Use the image's removal control only when you intend to delete that attachment from the item. If an upload fails, check the reported validation error and retry the affected image. The [API reference](https://conversionlab.app/docs/developer/api) additionally documents document and link attachments and its own upload constraints for programmatic workflows. ## Discuss work Open **Comments** on an idea, insight, or experiment. Post a comment, reply in a thread, or mention a teammate using the editor. Comments require a plan that includes collaboration: Team, Agency Starter, Agency Pro, and Enterprise currently include comments; Free, Solo, and Freelance do not. Team membership is required to participate. You can edit your own comments. Owners and admins can also remove other members' comments; that does not let them edit another person's wording. ## Review history Use **Activity** to see the recorded changes to an item. Activity and comments serve different purposes: history records actions, while discussion explains intent and decisions. Notification delivery depends on your [account preferences](https://conversionlab.app/docs/team-administration/profile-notifications) and, for Slack, the project's [Slack notification settings](https://conversionlab.app/docs/integrations/slack). A successful comment does not guarantee that every teammate has enabled alerts. --- Source: https://conversionlab.app/docs/concepts/definitions # Define pages, audiences, labels, and tags Give project work a consistent vocabulary for targeting, categorization, and filtering. Project definitions let your team describe work consistently instead of repeating slightly different names on each item. Select the intended project, then open **Settings → Project → Definitions**. ## Pages and audiences A **Page** identifies a website area relevant to research or experiments. An **Audience** identifies a visitor group. Create entries with recognizable names and enough description to distinguish similar concepts. 1. Open **Pages** or **Audiences**. 2. Choose **New page** or **New audience**, complete the fields, and save. 3. Link the definition to work that concerns it. Use **Import Pages** or **Import Audiences** when the selected project has a provider with discoverable data. An import creates or maps a definition; it does not prove that an experiment on that page has run. See [testing platform integrations](https://conversionlab.app/docs/integrations/testing-platforms). ## Labels and tags **Insight Labels** provide a named, colored classification for insights. **Tags** provide reusable categorization; choose the tag type offered by the editor for its intended use. Use the same definition when two items should appear together in filtering and review. Edit existing definitions from their settings table. Deletion dialogs identify permanent changes; check linked work and update your team's naming convention before removing a definition others use. ## States and metrics Idea and experiment states describe progress rather than evidence. Their customization is governed by plan availability; see [states and workflows](https://conversionlab.app/docs/ideas/states). Metrics define what you measure and how improvements should be interpreted; see [metrics](https://conversionlab.app/docs/concepts/metrics). If a selector is empty, confirm that the definition exists in the selected project and that filters are cleared. --- Source: https://conversionlab.app/docs/concepts # Core concepts Understand the work model and configure the vocabulary your project uses. ## Choose a task [Understand the research and experimentation model](https://conversionlab.app/docs/concepts/work-model) Know when to use observations, insights, learnings, ideas, and experiments. [Create and manage projects](https://conversionlab.app/docs/concepts/projects) Group related work and manage a project’s name, appearance, and settings. [Define pages, audiences, labels, and tags](https://conversionlab.app/docs/concepts/definitions) Give project work a consistent vocabulary for targeting, categorization, and filtering. [Define metrics and winning direction](https://conversionlab.app/docs/concepts/metrics) Create meaningful measurement definitions and map provider metrics. [Collaborate with comments, attachments, and activity](https://conversionlab.app/docs/concepts/collaboration) Keep discussion and evidence next to the work they describe. --- Source: https://conversionlab.app/docs/concepts/metrics # Define metrics and winning direction Create meaningful measurement definitions and map provider metrics. A metric is an outcome your team tracks, such as completed orders or revenue. Create reusable metrics before linking them to ideas and experiments. ## Add a metric 1. Select the project and open **Settings → Project → Metrics**. 2. Choose **New metric** and enter its name and description. 3. Select the metric type and winning direction. 4. Save, then link it to the appropriate idea or experiment. Winning direction records whether a higher or lower value is preferable. A metric's definition matters: a rate, count, and monetary value are different measurements. Use the type that matches the underlying provider data. ![Acorn Store metric definitions showing checkout completion and revenue per visitor with increasing winning direction, and checkout abandonment with decreasing winning direction.](https://conversionlab.app/docs/images/workflows/metrics.webp) ## Import and map metrics Use the metric import action when a connected provider supports discovery. Review the external metric you select instead of relying only on similar names. A linked indicator identifies a metric connected to a provider. For experiment reporting, the primary metric and every provider variation must be mapped correctly. The current fixed-horizon statistical report supports rate-per-user primary metrics. Other metric definitions can be stored, but do not assume every type has statistical analysis support. ## Change a definition deliberately Editing a name or description helps explain the existing measurement. Changing its type, winning direction, or provider mapping changes how teammates understand it. Review connected experiments and their result status after such a change. If results show **Primary metric is not supported yet** or **Result mapping is incomplete**, follow [result troubleshooting](https://conversionlab.app/docs/troubleshooting/results). --- Source: https://conversionlab.app/docs/concepts/projects # Create and manage projects Group related work and manage a project’s name, appearance, and settings. A project groups a team's research, ideas, experiments, surveys, and definitions. Use separate projects when the work needs distinct settings or a separate working context. ![Project Settings for the fictional Acorn Store project, showing its cover, color, and name fields.](https://conversionlab.app/docs/images/workflows/projects.webp) ## Create or select a project Owners and admins can create and manage projects, subject to the team's plan allowance. A new team receives a Default Project during creation, so check for that project before adding another. Use the project area in the sidebar to select an existing project or open the create-project action. Give a new project a recognizable name. After creation, select it before adding definitions and work items. ## Change project settings 1. Select the project in the sidebar. 2. Open **Settings → Project → General**. 3. Update the name, color, and cover image and wait for the save to complete. For an existing project's cover, use an image no larger than 1 MB. 4. Configure [definitions](https://conversionlab.app/docs/concepts/definitions), [metrics](https://conversionlab.app/docs/concepts/metrics), [taxonomy](https://conversionlab.app/docs/team-administration/taxonomy), and [integrations](https://conversionlab.app/docs/integrations) for that project as needed. Project settings follow the selected project. Check the project name in the settings navigation before changing shared definitions. ## Delete a project The delete action in Project Settings removes the project and its associated data. The confirmation identifies it as permanent. Move or preserve any work you still need before confirming, and verify the project name carefully. If project creation is unavailable, check your owner/admin role and the current plan allowance in [Billing](https://conversionlab.app/docs/team-administration/billing). A billing account in read-only mode allows browsing but blocks changes. --- Source: https://conversionlab.app/docs/concepts/work-model # Understand the research and experimentation model Know when to use observations, insights, learnings, ideas, and experiments. Each work item answers a different question. Keeping those questions separate makes it easier to trace a decision back to evidence. | Item | Use it for | Example | | ----------- | ---------------------------------------------------------- | ------------------------------------------------------------ | | Observation | What was seen or reported in a source | Three interviewees asked about delivery charges. | | Insight | What the evidence suggests about a problem or opportunity | Unclear delivery costs make the total price hard to assess. | | Learning | What the team now understands, with context and confidence | Delivery information helped first-time buyers in this test. | | Idea | A possible change worth considering | Put delivery information beside the price. | | Experiment | A planned test of a hypothesis | Compare the current page with explicit delivery information. | ## Link the work An observation can support an insight. Insights can connect to ideas, experiments, and learnings. These relationships preserve the reason for an idea and make later outcomes discoverable. A **Team** is the shared workspace and access boundary. A **Project** organizes related optimization work within it. Pages, audiences, metrics, tags, labels, and states give project work a consistent vocabulary. ## Keep source and interpretation distinguishable Record the source and confidence when the field is available. Avoid copying the same statement into every work-item type: the observation captures evidence, the insight interprets it, and the idea proposes action. A learning should retain the conditions under which it was supported. [Research guides](https://conversionlab.app/docs/research) explain the links in detail. [Project definitions](https://conversionlab.app/docs/concepts/definitions) explain the fields used to group and measure your work. --- Source: https://conversionlab.app/docs/developer/ai-readable-docs # Use documentation in external AI tools Copy an article or retrieve Markdown, LLM indexes, and OpenAPI. The public documentation can be consumed without connecting a client to private team data. Use the article source when you want an AI tool to understand product behavior or help write an integration. ## Copy the right format Open the **Page actions** menu (the three dots beside the article title) to choose **Copy Markdown**, **Copy content**, or **View Markdown**. **Copy Markdown** copies the article in Markdown, including headings, lists, code, links, and image descriptions. It excludes site navigation. **Copy content** copies the formatted article for a document or rich-text destination. Where the browser or clipboard does not support rich HTML, a plain-text fallback remains available. ## Fetch a public export - [llms.txt](https://conversionlab.app/docs/llms.txt) lists the documentation and article links. - [llms-full.txt](https://conversionlab.app/docs/llms-full.txt) contains the full published documentation text. - [OpenAPI](https://conversionlab.app/docs/openapi.json) describes the supported REST contract. - Each article has a Markdown export available through its article controls or Markdown URL. Use the article's stable link when citing a behavior. Images provide supporting visual context, while the written instructions and image descriptions remain useful to a text-only client. ## Separate instructions from access These exports describe how ConversionLab works. They do not contain your team's private projects or credentials, and reading them does not grant permission to change work. Use [MCP](https://conversionlab.app/docs/developer/mcp-setup) or the [REST API](https://conversionlab.app/docs/developer/authentication) only when the client needs authenticated team access. API and MCP reference exports contain their parameter, schema, and example content in text so the same contract is available to readers and tools. --- Source: https://conversionlab.app/docs/developer/api-conventions # Use REST queries, uploads, and errors Build clients around each endpoint’s supported fields and response contract. The [endpoint reference](https://conversionlab.app/docs/developer/api) is the authority for each operation's method, path, parameters, schemas, and response examples. Existing endpoints use `/api/...` paths and retain their existing response shapes. ## Query list endpoints Many core resource lists support bracketed filters, comma-separated includes, and sorting. For example, the ideas list accepts a project filter, priority sorting, and related insights: ```bash curl --get --fail-with-body \ "$CONVERSIONLAB_API_ORIGIN/api/ideas" \ --header "Authorization: Bearer $CONVERSIONLAB_TOKEN" \ --header 'Accept: application/json' \ --data-urlencode 'filter[project_id]=1' \ --data-urlencode 'sort=-priority_score' \ --data-urlencode 'include=insights' \ --data-urlencode 'page[number]=1' \ --data-urlencode 'page[size]=20' ``` Use an ID returned by your team's project list instead of the illustrative `1`. A leading minus requests descending order. Allowed filters, sorts, and includes differ by endpoint; unsupported names can be rejected. Core lists using the JSON paginator accept `page[number]` and `page[size]`, with a default and maximum page size of 30 in the current configuration. Other lists and reports can use different pagination or return a bounded collection; follow the operation's parameters and response links rather than assuming a single paginator everywhere. Resource responses commonly wrap the record or collection in `data`. Related fields may appear only when included. `/api/user`, summaries, exports, and custom actions can have different shapes; parse their documented schemas. ## Send writes and uploads Send JSON with `Content-Type: application/json` for JSON operations. Use the operation's exact required IDs, enums, and field limits. Linked records must belong to the permitted project and team. File uploads use multipart form data where specified. Ordinary attachments accept a file up to 10 MB and one of the documented JPEG, PNG, GIF, PDF, Word, or Excel formats. Link attachments use a URL instead of a file. An upload also identifies its project and attachable record; use the exact attachment type and fields in the reference. Some updates have a documented POST alias for multipart compatibility. Use a method listed for that operation rather than inventing an alternative route. Bulk and lifecycle actions have their own request fields and effects; inspect the response before treating the whole selection as complete. ## Handle failures | HTTP status | Typical client response | | ----------- | --------------------------------------------------------------------- | | 400 | Correct malformed or unsupported query parameters. | | 401 | Replace missing, expired, or revoked authentication. | | 402 | Resolve a read-only subscription state before retrying a write. | | 403 | Check token ability, team membership, role, and feature availability. | | 404 | Check the resource ID in the token's team context. | | 422 | Read the validation message and field errors; correct the request. | | 429 | Respect returned retry information and slow down. | | 5xx | Preserve error context and retry cautiously after recovery. | The configured default bearer-token rate limit is 120 requests per minute; deployments can override it. Read the returned rate-limit and retry headers when present. Do not retry validation or permission failures unchanged. For a timed-out create, check whether the item was created before resending the same write. The public contract does not promise universal idempotency keys for mutations. --- Source: https://conversionlab.app/docs/developer/api/delete-attachments-attachment # Delete attachment DELETE /attachments/{attachment}. Parameters, permissions, request and response schemas. `DELETE /attachments/{attachment}` Delete attachment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `attachment` | path | Yes | The attachment ID | ### attachment ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/attachments/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-audiences-audience # Delete audience DELETE /audiences/{audience}. Parameters, permissions, request and response schemas. `DELETE /audiences/{audience}` Delete audience. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ---------- | -------- | -------- | --------------- | | `audience` | path | Yes | The audience ID | ### audience ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/audiences/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-comments-comment # Delete comment DELETE /comments/{comment}. Parameters, permissions, request and response schemas. `DELETE /comments/{comment}` Delete comment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | -------------- | | `comment` | path | Yes | The comment ID | ### comment ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/comments/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-experiment-states-experiment-state # Delete experiment state DELETE /experiment-states/{experiment\_state}. Parameters, permissions, request and response schemas. `DELETE /experiment-states/{experiment_state}` Delete experiment state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------------ | -------- | -------- | ----------------------- | | `experiment_state` | path | Yes | The experiment state ID | ### experiment\_state ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/experiment-states/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-experiments-experiment # Delete experiment DELETE /experiments/{experiment}. Parameters, permissions, request and response schemas. `DELETE /experiments/{experiment}` Delete experiment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `experiment` | path | Yes | The experiment ID | ### experiment ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/experiments/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-forms-form-responses # Reset survey responses DELETE /forms/{form}/responses. Parameters, permissions, request and response schemas. `DELETE /forms/{form}/responses` Reset survey responses. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. This permanently removes data. Read the request requirements and verify the target before sending. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `form` | path | Yes | The form ID | ### form ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/forms/1/responses' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-forms-form # Delete form DELETE /forms/{form}. Parameters, permissions, request and response schemas. `DELETE /forms/{form}` Delete form. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `form` | path | Yes | The form ID | ### form ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/forms/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-idea-states-idea-state # Delete idea state DELETE /idea-states/{idea\_state}. Parameters, permissions, request and response schemas. `DELETE /idea-states/{idea_state}` Delete idea state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `idea_state` | path | Yes | The idea state ID | ### idea\_state ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/idea-states/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "maxProperties": 0, "description": "Empty JSON object returned after deletion." } ``` ```json {} ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-ideas-idea # Delete idea DELETE /ideas/{idea}. Parameters, permissions, request and response schemas. `DELETE /ideas/{idea}` Delete idea. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `idea` | path | Yes | The idea ID | ### idea ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/ideas/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "const": "Idea deleted successfully" } }, "required": [ "message" ] } ``` ```json { "message": "Idea deleted successfully" } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-insight-labels-insight-label # Delete insight label DELETE /insight-labels/{insight\_label}. Parameters, permissions, request and response schemas. `DELETE /insight-labels/{insight_label}` Delete insight label. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------------- | -------- | -------- | -------------------- | | `insight_label` | path | Yes | The insight label ID | ### insight\_label ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/insight-labels/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-insights-insight # Delete insight DELETE /insights/{insight}. Parameters, permissions, request and response schemas. `DELETE /insights/{insight}` Delete insight. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | -------------- | | `insight` | path | Yes | The insight ID | ### insight ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/insights/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-learnings-learning # Delete learning DELETE /learnings/{learning}. Parameters, permissions, request and response schemas. `DELETE /learnings/{learning}` Delete learning. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ---------- | -------- | -------- | --------------- | | `learning` | path | Yes | The learning ID | ### learning ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/learnings/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-metrics-metric # Delete metric DELETE /metrics/{metric}. Parameters, permissions, request and response schemas. `DELETE /metrics/{metric}` Delete metric. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | -------- | -------- | -------- | ------------- | | `metric` | path | Yes | The metric ID | ### metric ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/metrics/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-observations-observation-force # Permanently delete an archived observation DELETE /observations/{observation}/force. Parameters, permissions, request and response schemas. `DELETE /observations/{observation}/force` Permanently delete an archived observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. This permanently removes data. Read the request requirements and verify the target before sending. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------- | -------- | -------- | ------------ | | `observation` | path | Yes | Observation. | ### observation ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/observations/1/force' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-observations-observation # Delete observation DELETE /observations/{observation}. Parameters, permissions, request and response schemas. `DELETE /observations/{observation}` Delete observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------- | -------- | -------- | ------------------ | | `observation` | path | Yes | The observation ID | ### observation ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/observations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-pages-page # Delete page DELETE /pages/{page}. Parameters, permissions, request and response schemas. `DELETE /pages/{page}` Delete page. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `page` | path | Yes | The page ID | ### page ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/pages/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-prio-models-prio-model # Delete prio model DELETE /prio-models/{prio\_model}. Parameters, permissions, request and response schemas. `DELETE /prio-models/{prio_model}` Delete prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------- | | `prio_model` | path | Yes | Prio Model. | | `project_id` | query | Yes | Project Id. | | `id` | query | Yes | Id. | ### prio\_model ```json { "type": "integer", "minimum": 1 } ``` ### project\_id ```json { "type": "integer" } ``` ### id ```json { "type": "integer" } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/prio-models/1?project_id=101&id=101' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "const": "Prioritization model removed successfully" } }, "required": [ "message" ] } ``` ```json { "message": "Prioritization model removed successfully" } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-projects-project # Delete project DELETE /projects/{project}. Parameters, permissions, request and response schemas. `DELETE /projects/{project}` Delete project. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | -------------- | | `project` | path | Yes | The project ID | ### project ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/projects/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-research-collections-research-collection # Delete research collection DELETE /research-collections/{research\_collection}. Parameters, permissions, request and response schemas. `DELETE /research-collections/{research_collection}` Delete research collection. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------------------- | -------- | -------- | -------------------------- | | `research_collection` | path | Yes | The research collection ID | ### research\_collection ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/research-collections/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-roadmap-annotations-roadmap-annotation # Delete roadmap annotation DELETE /roadmap-annotations/{roadmap\_annotation}. Parameters, permissions, request and response schemas. `DELETE /roadmap-annotations/{roadmap_annotation}` Delete roadmap annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | -------------------- | -------- | -------- | ------------------------- | | `roadmap_annotation` | path | Yes | The roadmap annotation ID | ### roadmap\_annotation ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/roadmap-annotations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-screen-annotations-screen-annotation # Delete screen annotation DELETE /screen-annotations/{screen\_annotation}. Parameters, permissions, request and response schemas. `DELETE /screen-annotations/{screen_annotation}` Delete screen annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------------- | -------- | -------- | ------------------------ | | `screen_annotation` | path | Yes | The screen annotation ID | ### screen\_annotation ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/screen-annotations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-screens-screen # Delete screen DELETE /screens/{screen}. Parameters, permissions, request and response schemas. `DELETE /screens/{screen}` Delete screen. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | -------- | -------- | -------- | ------------- | | `screen` | path | Yes | The screen ID | ### screen ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/screens/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-tags-tag # Delete tag DELETE /tags/{tag}. Parameters, permissions, request and response schemas. `DELETE /tags/{tag}` Delete tag. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ----- | -------- | -------- | ----------- | | `tag` | path | Yes | The tag ID | ### tag ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/tags/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/delete-variations-variation # Delete variation DELETE /variations/{variation}. Parameters, permissions, request and response schemas. `DELETE /variations/{variation}` Delete variation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ---------------- | | `variation` | path | Yes | The variation ID | | `project_id` | query | Yes | Project Id. | ### variation ```json { "type": "integer", "minimum": 1 } ``` ### project\_id ```json { "type": "integer" } ``` ## Example request ```bash curl --request DELETE 'https://api.example.test/api/variations/1?project_id=101' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-activities # List activities GET /activities. Parameters, permissions, request and response schemas. `GET /activities` List activities. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------- | -------- | -------- | ------------- | | `subject_type` | query | Yes | Subject Type. | | `subject_id` | query | Yes | Subject Id. | | `period` | query | No | Period. | | `per_page` | query | No | Per Page. | | `sort` | query | No | Sort. | ### subject\_type ```json { "type": "string", "enum": [ "goal", "tag", "experiment", "idea", "insight", "learning", "observation", "page", "audience", "project", "team", "user", "variation", "activity", "comment", "form", "form_question", "form_response", "form_answer", "form_step", "form_response_summary", "project_lookup" ] } ``` ### subject\_id ```json { "type": "integer", "minimum": 1 } ``` ### period ```json { "type": "string", "maxLength": 50 } ``` ### per\_page ```json { "type": "integer", "minimum": 1, "maximum": 100 } ``` ### sort ```json { "type": [ "string", "null" ], "enum": [ "id", "-id", "created_at", "-created_at", null ] } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/activities?subject_type=goal&subject_id=101' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Paginated set of `ActivityResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "log_name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "subject_type": { "type": [ "string", "null" ] }, "subject_id": { "type": [ "integer", "null" ] }, "event": { "type": [ "string", "null" ] }, "causer_type": { "type": [ "string", "null" ] }, "causer_id": { "type": [ "integer", "null" ] }, "properties": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "batch_uuid": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "subject": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "log_name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "subject_type": { "type": [ "string", "null" ] }, "event": { "type": [ "string", "null" ] }, "subject_id": { "type": [ "integer", "null" ] }, "causer_type": { "type": [ "string", "null" ] }, "causer_id": { "type": [ "integer", "null" ] }, "properties": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "batch_uuid": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "log_name", "description", "subject_type", "event", "subject_id", "causer_type", "causer_id", "properties", "batch_uuid", "created_at", "updated_at" ], "title": "Activity", "description": "Relationships" }, { "type": "null" } ] }, "causer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "log_name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "subject_type": { "type": [ "string", "null" ] }, "event": { "type": [ "string", "null" ] }, "subject_id": { "type": [ "integer", "null" ] }, "causer_type": { "type": [ "string", "null" ] }, "causer_id": { "type": [ "integer", "null" ] }, "properties": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "batch_uuid": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "log_name", "description", "subject_type", "event", "subject_id", "causer_type", "causer_id", "properties", "batch_uuid", "created_at", "updated_at" ], "title": "Activity" }, { "type": "null" } ] } }, "required": [ "id", "log_name", "description", "subject_type", "subject_id", "event", "causer_type", "causer_id", "properties", "batch_uuid", "created_at", "updated_at" ], "title": "ActivityResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "log_name": null, "description": "Show the expected delivery date before payment.", "subject_type": null, "subject_id": null, "event": null, "causer_type": null, "causer_id": null, "properties": null, "batch_uuid": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-attachments-attachment # Get attachment GET /attachments/{attachment}. Parameters, permissions, request and response schemas. `GET /attachments/{attachment}` Get attachment. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `attachment` | path | Yes | The attachment ID | ### attachment ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/attachments/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `AttachmentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "file_type": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "image", "document", "link" ], "title": "AttachmentType" }, "url": { "type": [ "string", "null" ] }, "attachable_type": { "type": "string" }, "attachable_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "file_type", "file_size", "type", "url", "attachable_type", "attachable_id", "created_at", "updated_at" ], "title": "AttachmentResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-attachments # List attachments GET /attachments. Parameters, permissions, request and response schemas. `GET /attachments` List attachments. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, name, created\_at, updated\_at. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[attachable_type]` | query | No | Filter by attachable\_type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[attachable_id]` | query | No | Filter by attachable\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `include` | query | No | Comma-separated relationships. Allowed: attachable. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[attachable\_type] ```json { "type": "string" } ``` ### filter\[attachable\_id] ```json { "type": "string" } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/attachments' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `AttachmentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "file_type": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "image", "document", "link" ], "title": "AttachmentType" }, "url": { "type": [ "string", "null" ] }, "attachable_type": { "type": "string" }, "attachable_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "file_type", "file_size", "type", "url", "attachable_type", "attachable_id", "created_at", "updated_at" ], "title": "AttachmentResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-audiences-audience # Get audience GET /audiences/{audience}. Parameters, permissions, request and response schemas. `GET /audiences/{audience}` Get audience. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ---------- | -------- | -------- | ---------------------------------------------------------------------------------------------- | | `audience` | path | Yes | The audience ID | | `include` | query | No | Comma-separated relationships or counts. Allowed: experimentsCount, ideasCount, insightsCount. | ### audience ```json { "type": "integer", "minimum": 1 } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/audiences/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `AudienceResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-audiences # List audiences GET /audiences. Parameters, permissions, request and response schemas. `GET /audiences` List audiences. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: project\_id, name, created\_at, updated\_at, experimentsCount, ideasCount, insightsCount. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[description]` | query | No | Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `include` | query | No | Comma-separated relationships. Allowed: experimentsCount, ideasCount, insightsCount. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[description] ```json { "type": "string" } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/audiences' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `AudienceResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-comments # List comments GET /comments. Parameters, permissions, request and response schemas. `GET /comments` List comments. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `commentable_type` | query | Yes | Commentable Type. | | `commentable_id` | query | Yes | Commentable Id. | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, created\_at, updated\_at. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[user_id]` | query | No | Filter by user\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### commentable\_type ```json { "type": "string", "enum": [ "insight", "idea", "experiment" ] } ``` ### commentable\_id ```json { "type": "integer", "minimum": 1 } ``` ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[user\_id] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/comments?commentable_type=insight&commentable_id=101' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `CommentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "body": { "type": "string" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "seat_type": { "type": [ "string", "null" ] }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "email", "role", "seat_type", "email_verified_at", "created_at", "updated_at", "last_login_at" ], "title": "UserResource" }, { "type": "null" } ] }, "user_id": { "type": [ "integer", "null" ] }, "parent_id": { "type": [ "integer", "null" ] }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/CommentResource" } }, "is_approved": { "type": "boolean" }, "commentable_type": { "type": "string" }, "commentable_id": { "type": "integer" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "body", "user_id", "parent_id", "is_approved", "commentable_type", "commentable_id", "can_edit", "can_delete", "created_at", "updated_at" ], "title": "CommentResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "body": "example", "user_id": null, "parent_id": null, "is_approved": true, "commentable_type": "example", "commentable_id": 101, "can_edit": true, "can_delete": true, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-daily-briefs-today # Get daily brief GET /daily-briefs/today. Parameters, permissions, request and response schemas. `GET /daily-briefs/today` Get daily brief. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. Returns retained content or data: null; this endpoint never generates a brief. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/daily-briefs/today' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "brief_date": { "type": "string" }, "content": { "type": "string" }, "generated_at": { "type": "string" }, "viewed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "brief_date", "content", "generated_at", "viewed_at" ] } }, "required": [ "data" ] } ``` ```json { "data": null } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-experiment-states-experiment-state # Get experiment state GET /experiment-states/{experiment\_state}. Parameters, permissions, request and response schemas. `GET /experiment-states/{experiment_state}` Get experiment state. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------------ | -------- | -------- | ----------------------- | | `experiment_state` | path | Yes | The experiment state ID | ### experiment\_state ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/experiment-states/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ExperimentStateResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "category": { "anyOf": [ { "type": "string", "enum": [ "draft", "live", "paused", "finished", "archived" ], "title": "ExperimentStateCategory" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "category", "order", "created_at", "updated_at" ], "title": "ExperimentStateResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "description": null, "category": null, "order": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-experiment-states # List experiment states GET /experiment-states. Parameters, permissions, request and response schemas. `GET /experiment-states` List experiment states. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project\_id, name, order. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[description]` | query | No | Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[order]` | query | No | Filter by order. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[description] ```json { "type": "string" } ``` ### filter\[order] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/experiment-states' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `ExperimentStateResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "category": { "anyOf": [ { "type": "string", "enum": [ "draft", "live", "paused", "finished", "archived" ], "title": "ExperimentStateCategory" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "category", "order", "created_at", "updated_at" ], "title": "ExperimentStateResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "project_id": null, "name": null, "description": null, "category": null, "order": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-experiments-experiment-approvals # List experiment approvals GET /experiments/{experiment}/approvals. Parameters, permissions, request and response schemas. `GET /experiments/{experiment}/approvals` List experiment approvals. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `experiment` | path | Yes | The experiment ID | ### experiment ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/experiments/1/approvals' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `ExperimentApprovalResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "data" ] } ``` ```json { "data": [ { "id": 101, "experiment_id": 101, "user_id": 101, "status": "example", "notes": null, "approved_at": "example", "created_at": null } ] } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-experiments-experiment-summary # Get the result report for experiment GET /experiments/{experiment}/summary. Parameters, permissions, request and response schemas. `GET /experiments/{experiment}/summary` Get the result report for experiment. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `experiment` | path | Yes | The experiment ID | | `alpha` | query | No | Alpha. | | `srm_alpha` | query | No | Srm Alpha. | ### experiment ```json { "type": "integer", "minimum": 1 } ``` ### alpha ```json { "type": "string" } ``` ### srm\_alpha ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/experiments/1/summary' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ExperimentReportResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "insufficient_data", "srm_detected", "incomplete_mapping", "unsupported_metric", "fixed_horizon_pending", "stale_source", "engine_unavailable", "invalid_configuration", "no_data" ] }, "status_reason": { "type": [ "string", "null" ] }, "alpha": { "type": [ "number", "null" ] }, "control_variation_id": { "type": [ "integer", "null" ] }, "method": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "const": "fixed_horizon_v1" }, "version": { "type": "string", "const": "1.0.0" }, "multiple_comparison_correction": { "type": "string", "const": "holm" } }, "required": [ "name", "version", "multiple_comparison_correction" ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "object", "properties": { "integration_id": { "type": "integer" }, "external_updated_at": { "type": [ "string", "null" ] }, "synced_at": { "type": [ "string", "null" ] } }, "required": [ "integration_id", "external_updated_at", "synced_at" ] }, { "type": "null" } ] }, "primary_metric": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "external_id": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "type", "external_id" ] }, { "type": "null" } ] }, "totals": { "type": "object", "properties": { "visitors": { "type": "integer" }, "conversions": { "type": "integer" }, "conversion_rate_percent": { "type": [ "number", "null" ] } }, "required": [ "visitors", "conversions", "conversion_rate_percent" ] }, "srm": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "insufficient_data" ] }, "alpha": { "type": "number" }, "chi_square": { "type": [ "number", "null" ] }, "degrees_of_freedom": { "type": "integer" }, "p_value": { "type": [ "number", "null" ] }, "is_srm": { "type": "boolean" }, "expected_counts": { "type": "array", "items": { "type": "number" } } }, "required": [ "status", "alpha", "chi_square", "degrees_of_freedom", "p_value", "is_srm", "expected_counts" ] }, { "type": "null" } ] }, "variations": { "type": "array", "items": { "type": "object", "properties": { "variation_id": { "type": "integer" }, "external_id": { "type": "string" }, "name": { "type": "string" }, "is_control": { "type": "boolean" }, "traffic_percentage": { "type": "number", "description": "Traffic share as a fraction: 0.5 means 50%." }, "visitors": { "type": "integer" }, "conversions": { "type": "integer" }, "conversion_rate_percent": { "type": [ "number", "null" ] }, "comparison_status": { "type": [ "string", "null" ], "enum": [ "available", "insufficient_data", null ] }, "test_method": { "type": [ "string", "null" ], "enum": [ "two_proportion_z", "fisher_exact", null ] }, "statistic": { "type": [ "number", "null" ] }, "p_value": { "type": [ "number", "null" ] }, "adjusted_p_value": { "type": [ "number", "null" ] }, "is_significant": { "type": [ "boolean", "null" ] }, "absolute_lift_percentage_points": { "type": [ "number", "null" ] }, "relative_lift_percent": { "type": [ "number", "null" ] }, "confidence_interval_percentage_points": { "anyOf": [ { "type": "object", "properties": { "lower": { "type": "number" }, "upper": { "type": "number" }, "confidence_level": { "type": "number" } }, "required": [ "lower", "upper", "confidence_level" ] }, { "type": "null" } ] } }, "required": [ "variation_id", "external_id", "name", "is_control", "traffic_percentage", "visitors", "conversions", "conversion_rate_percent", "comparison_status", "test_method", "statistic", "p_value", "adjusted_p_value", "is_significant", "absolute_lift_percentage_points", "relative_lift_percent", "confidence_interval_percentage_points" ] } } }, "required": [ "status", "status_reason", "alpha", "control_variation_id", "method", "source", "primary_metric", "totals", "srm", "variations" ], "description": "Fixed-horizon experiment report. Check status before interpreting significance; descriptive totals remain available for some unavailable states. Rates/lifts ending in percent use percent units; traffic_percentage uses a fraction.", "example": { "status": "no_data", "status_reason": "No synced experiment result is available.", "alpha": null, "control_variation_id": null, "method": null, "source": null, "primary_metric": null, "totals": { "visitors": 0, "conversions": 0, "conversion_rate_percent": null }, "srm": null, "variations": [] } } }, "required": [ "data" ] } ``` ```json { "data": { "status": "no_data", "status_reason": "No synced experiment result is available.", "alpha": null, "control_variation_id": null, "method": null, "source": null, "primary_metric": null, "totals": { "visitors": 0, "conversions": 0, "conversion_rate_percent": null }, "srm": null, "variations": [] } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-experiments-experiment-timeseries # Get result time series for experiment GET /experiments/{experiment}/timeseries. Parameters, permissions, request and response schemas. `GET /experiments/{experiment}/timeseries` Get result time series for experiment. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `experiment` | path | Yes | The experiment ID | | `start` | query | No | Start. | | `end` | query | No | End. | ### experiment ```json { "type": "integer", "minimum": 1 } ``` ### start ```json { "type": "string", "format": "date-time" } ``` ### end ```json { "type": "string", "format": "date-time" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/experiments/1/timeseries' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `ExperimentTimeseriesResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "variation_id": { "type": "integer" }, "name": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "format": "date" }, "visitors": { "type": "integer", "minimum": 0 }, "conversions": { "type": "integer", "minimum": 0 }, "conversion_rate": { "type": [ "number", "null" ], "description": "Conversion rate as a percentage, not a fraction." } }, "required": [ "date", "visitors", "conversions", "conversion_rate" ] } } }, "required": [ "variation_id", "name", "points" ] } } }, "required": [ "data" ] } ``` ```json { "data": [ { "variation_id": 101, "name": "Checkout delivery estimate", "points": [ { "date": null, "visitors": 1, "conversions": 1, "conversion_rate": null } ] } ] } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-experiments-experiment # Get experiment GET /experiments/{experiment}. Parameters, permissions, request and response schemas. `GET /experiments/{experiment}` Get experiment. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | -------------------------------------------------------------------------------------------------------- | | `experiment` | path | Yes | The experiment ID | | `include` | query | No | Comma-separated relationships or counts. Allowed: ideas, pages, audiences, insights, metrics, approvals. | ### experiment ```json { "type": "integer", "minimum": 1 } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/experiments/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ExperimentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-experiments # List experiments GET /experiments. Parameters, permissions, request and response schemas. `GET /experiments` List experiments. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project\_id, type, state\_id, custom\_id, name, start\_date, end\_date, user\_id. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[type]` | query | No | Filter by type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[state_id]` | query | No | Filter by state\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[custom_id]` | query | No | Filter by custom\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[user_id]` | query | No | Filter by user\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `include` | query | No | Comma-separated relationships. Allowed: audiences, ideas, insights, metrics, pages, state, variations, user, ideasCount, insightsCount. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[type] ```json { "type": "string" } ``` ### filter\[state\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[custom\_id] ```json { "type": "string" } ``` ### filter\[user\_id] ```json { "type": "string" } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/experiments' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `ExperimentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-forms-form-response-summary # Get form GET /forms/{form}/response-summary. Parameters, permissions, request and response schemas. `GET /forms/{form}/response-summary` Get form. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------- | -------- | -------- | ------------- | | `form` | path | Yes | The form ID | | `sample_limit` | query | No | Sample Limit. | | `theme_limit` | query | No | Theme Limit. | ### form ```json { "type": "integer", "minimum": 1 } ``` ### sample\_limit ```json { "type": "integer", "minimum": 1, "maximum": 20 } ``` ### theme\_limit ```json { "type": "integer", "minimum": 0, "maximum": 10 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/forms/1/response-summary' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "form_id": { "type": "integer" }, "generated_at": { "type": "string" }, "totals": { "type": "object", "properties": { "responses": { "type": "integer", "minimum": 0 }, "submitted": { "type": "integer", "minimum": 0 }, "partial": { "type": "integer", "minimum": 0 }, "questions": { "type": "integer", "minimum": 0 }, "answers": { "type": "integer", "minimum": 0 }, "completion_rate": { "type": "number" }, "answer_rate": { "type": "number" } }, "required": [ "responses", "submitted", "partial", "questions", "answers", "completion_rate", "answer_rate" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "step_title": { "type": [ "string", "null" ] }, "responses": { "type": "object", "properties": { "answered": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "response_rate": { "type": "number" } }, "required": [ "answered", "skipped", "response_rate" ] }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "percentage": { "type": "number" } }, "required": [ "value", "label", "count", "percentage" ] } }, "metrics": { "anyOf": [ { "type": "object", "properties": { "average": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" }, "nps": { "type": "object", "properties": { "score": { "type": "integer" }, "promoters": { "type": "integer", "minimum": 0 }, "passives": { "type": "integer", "minimum": 0 }, "detractors": { "type": "integer", "minimum": 0 } }, "required": [ "score", "promoters", "passives", "detractors" ] } }, "required": [ "average", "min", "max" ] }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 }, { "type": "object", "properties": { "emoji": { "type": "object", "properties": { "average_score": { "type": "number" }, "max_score": { "type": "integer" }, "positive": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer" }, "negative": { "type": "integer", "minimum": 0 }, "scale": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "integer" }, "count": { "type": "integer" }, "percentage": { "type": "number" } }, "required": [ "value", "label", "score", "count", "percentage" ] } }, "top_reaction": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "integer" }, "count": { "type": "integer" }, "percentage": { "type": "number" } }, "required": [ "value", "label", "score", "count", "percentage" ] } }, "required": [ "average_score", "max_score", "positive", "neutral", "negative", "scale", "top_reaction" ] } }, "required": [ "emoji" ] } ] }, "theme_candidates": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "integer" }, "examples": { "type": "array", "items": { "type": "string" } } }, "required": [ "label", "count", "examples" ] } }, "samples": { "type": "array", "items": { "type": "object", "properties": { "answer_id": { "type": "integer" }, "response_id": { "type": "integer" }, "status": { "type": "string" }, "value": { "type": "string" }, "raw_value": { "type": [ "string", "null" ] }, "page_url": { "type": [ "string", "null" ] }, "submitted_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "answer_id", "response_id", "status", "value", "raw_value", "page_url", "submitted_at", "updated_at" ] } } }, "required": [ "id", "title", "description", "type", "step_title", "responses", "distribution", "metrics", "theme_candidates", "samples" ] } } }, "required": [ "form_id", "generated_at", "totals", "questions" ] } }, "required": [ "data" ] } ``` ```json { "data": { "form_id": 101, "generated_at": "example", "totals": { "responses": 1, "submitted": 1, "partial": 1, "questions": 1, "answers": 1, "completion_rate": 1, "answer_rate": 1 }, "questions": [ { "id": 101, "title": "Checkout delivery estimate", "description": null, "type": "example", "step_title": null, "responses": { "answered": 1, "skipped": 1, "response_rate": 1 }, "distribution": [ { "value": "example", "label": "example", "count": 1, "percentage": 1 } ], "metrics": { "average": 1, "min": 1, "max": 1 }, "theme_candidates": [ { "label": "example", "count": 1, "examples": [] } ], "samples": [ { "answer_id": 101, "response_id": 101, "status": "example", "value": "example", "raw_value": null, "page_url": null, "submitted_at": null, "updated_at": null } ] } ] } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-forms-form-responses-export # Export responses for form GET /forms/{form}/responses/export. Parameters, permissions, request and response schemas. `GET /forms/{form}/responses/export` Export responses for form. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ---------------- | -------- | -------- | ---------------- | | `form` | path | Yes | The form ID | | `format` | query | Yes | Format. | | `filter[status]` | query | No | Filter\[Status]. | ### form ```json { "type": "integer", "minimum": 1 } ``` ### format ```json { "type": "string", "enum": [ "csv", "xlsx" ] } ``` ### filter\[status] ```json { "anyOf": [ { "type": "string", "enum": [ "partial", "submitted" ], "title": "FormResponseStatus" }, { "type": "null" } ] } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/forms/1/responses/export?format=csv' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Response headers: ```json { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } ``` Content type: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`. ```json { "type": "string", "format": "binary" } ``` Content type: `text/csv; charset=UTF-8`. ```json { "type": "string", "format": "binary" } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-forms-form-responses # List forms GET /forms/{form}/responses. Parameters, permissions, request and response schemas. `GET /forms/{form}/responses` List forms. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ---------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `form` | path | Yes | The form ID | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, status, submitted\_at, created\_at, updated\_at. | | `filter[status]` | query | No | Filter by status. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### form ```json { "type": "integer", "minimum": 1 } ``` ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[status] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/forms/1/responses' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `FormResponseResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "response_key": { "type": [ "string", "null" ] }, "respondent_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "page_url": { "type": [ "string", "null" ] }, "user_agent": { "type": [ "string", "null" ] }, "referrer": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "viewport_width": { "type": [ "integer", "null" ] }, "viewport_height": { "type": [ "integer", "null" ] }, "screen_width": { "type": [ "integer", "null" ] }, "screen_height": { "type": [ "integer", "null" ] }, "client_type": { "type": [ "string", "null" ] }, "browser_name": { "type": [ "string", "null" ] }, "browser_version": { "type": [ "string", "null" ] }, "os_name": { "type": [ "string", "null" ] }, "os_version": { "type": [ "string", "null" ] }, "device_type": { "type": [ "string", "null" ] }, "is_bot": { "type": "boolean" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_response_id": { "type": "integer" }, "form_question_id": { "type": "integer" }, "value": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_response_id", "form_question_id", "value", "created_at", "updated_at" ], "title": "FormAnswerResource" } }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "response_key", "respondent_id", "status", "page_url", "user_agent", "referrer", "language", "timezone", "viewport_width", "viewport_height", "screen_width", "screen_height", "client_type", "browser_name", "browser_version", "os_name", "os_version", "device_type", "is_bot", "submitted_at", "created_at", "updated_at" ], "title": "FormResponseResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "form_id": 101, "response_key": null, "respondent_id": null, "status": "example", "page_url": null, "user_agent": null, "referrer": null, "language": null, "timezone": null, "viewport_width": null, "viewport_height": null, "screen_width": null, "screen_height": null, "client_type": null, "browser_name": null, "browser_version": null, "os_name": null, "os_version": null, "device_type": null, "is_bot": true, "submitted_at": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-forms-form # Get form GET /forms/{form}. Parameters, permissions, request and response schemas. `GET /forms/{form}` Get form. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `form` | path | Yes | The form ID | ### form ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/forms/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `FormResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "widget", "inline", "link" ], "title": "FormType" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "FormStatus" }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "title", "description", "order", "created_at", "updated_at" ], "title": "FormStepResource" } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "responses_count": { "type": "integer" }, "submitted_responses_count": { "type": "integer", "minimum": 0 }, "partial_responses_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "public_id", "project_id", "name", "description", "type", "status", "settings", "created_at", "updated_at" ], "title": "FormResource" }, { "type": "object", "required": [ "steps" ] } ] } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "steps": [ { "id": 101, "form_id": 101, "title": null, "description": null, "order": 1, "created_at": null, "updated_at": null } ], "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-forms # List forms GET /forms. Parameters, permissions, request and response schemas. `GET /forms` List forms. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, name, status, created\_at. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[status]` | query | No | Filter by status. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[type]` | query | No | Filter by type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[status] ```json { "type": "string" } ``` ### filter\[type] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/forms' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `FormResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "widget", "inline", "link" ], "title": "FormType" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "FormStatus" }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "title", "description", "order", "created_at", "updated_at" ], "title": "FormStepResource" } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "responses_count": { "type": "integer" }, "submitted_responses_count": { "type": "integer", "minimum": 0 }, "partial_responses_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "public_id", "project_id", "name", "description", "type", "status", "settings", "created_at", "updated_at" ], "title": "FormResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-idea-states-idea-state # Get idea state GET /idea-states/{idea\_state}. Parameters, permissions, request and response schemas. `GET /idea-states/{idea_state}` Get idea state. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `idea_state` | path | Yes | The idea state ID | ### idea\_state ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/idea-states/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `IdeaStateResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "description": null, "color": null, "order": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-idea-states # List idea states GET /idea-states. Parameters, permissions, request and response schemas. `GET /idea-states` List idea states. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project\_id, name, order. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[description]` | query | No | Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[order]` | query | No | Filter by order. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[description] ```json { "type": "string" } ``` ### filter\[order] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/idea-states' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `IdeaStateResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "project_id": null, "name": null, "description": null, "color": null, "order": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-ideas-idea # Get idea GET /ideas/{idea}. Parameters, permissions, request and response schemas. `GET /ideas/{idea}` Get idea. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | --------------------------------------------------------------------------------------------------- | | `idea` | path | Yes | The idea ID | | `include` | query | No | Comma-separated relationships or counts. Allowed: audiences, experiments, insights, metrics, pages. | ### idea ```json { "type": "integer", "minimum": 1 } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/ideas/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `IdeaResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "audit", "insight", "experiment", "form", "api" ], "title": "IdeaSourceType" }, { "type": "null" } ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_name": { "type": [ "string", "null" ] }, "priority_values": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_score": { "type": [ "number", "null" ] }, "priority_details": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_calculated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" } }, "experiments_count": { "type": "integer" }, "insights_count": { "type": "integer" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "project_id", "state_id", "name", "description", "hypothesis", "user_id", "source", "source_id", "source_item_key", "source_name", "priority_values", "priority_score", "priority_details", "priority_calculated_at", "created_at", "updated_at" ], "title": "IdeaResource" }, { "type": "object", "required": [ "audiences" ] } ] } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "project_id": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_name": null, "priority_values": null, "priority_score": null, "priority_details": null, "priority_calculated_at": null, "created_at": null, "updated_at": null, "audiences": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } ] } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-ideas # List ideas GET /ideas. Parameters, permissions, request and response schemas. `GET /ideas` List ideas. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | query | No | Include\[]. | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, state\_id, custom\_id, name, priority\_score. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[state_id]` | query | No | Filter by state\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[custom_id]` | query | No | Filter by custom\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[user_id]` | query | No | Filter by user\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `include` | query | No | Comma-separated relationships. Allowed: audiences, experiments, insights, metrics, pages, state, experimentsCount, insightsCount. | ### include\[] ```json { "type": "array", "enum": [ "audiences", "experiments", "insights", "metrics", "pages", "state", "ideasCount", "experimentsCount", "insightsCount" ], "items": { "type": "string", "enum": [ "audiences", "experiments", "insights", "metrics", "pages", "state", "ideasCount", "experimentsCount", "insightsCount" ] } } ``` ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[state\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[custom\_id] ```json { "type": "string" } ``` ### filter\[user\_id] ```json { "type": "string" } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/ideas' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `IdeaResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "audit", "insight", "experiment", "form", "api" ], "title": "IdeaSourceType" }, { "type": "null" } ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_name": { "type": [ "string", "null" ] }, "priority_values": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_score": { "type": [ "number", "null" ] }, "priority_details": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_calculated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" } }, "experiments_count": { "type": "integer" }, "insights_count": { "type": "integer" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "project_id", "state_id", "name", "description", "hypothesis", "user_id", "source", "source_id", "source_item_key", "source_name", "priority_values", "priority_score", "priority_details", "priority_calculated_at", "created_at", "updated_at" ], "title": "IdeaResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "project_id": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_name": null, "priority_values": null, "priority_score": null, "priority_details": null, "priority_calculated_at": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-insight-labels-insight-label # Get insight label GET /insight-labels/{insight\_label}. Parameters, permissions, request and response schemas. `GET /insight-labels/{insight_label}` Get insight label. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------------- | -------- | -------- | -------------------- | | `insight_label` | path | Yes | The insight label ID | ### insight\_label ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/insight-labels/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `InsightLabelResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "InsightLabelColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "color", "order", "created_at", "updated_at", "deleted_at" ], "title": "InsightLabelResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "color": null, "order": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-insight-labels # List insight labels GET /insight-labels. Parameters, permissions, request and response schemas. `GET /insight-labels` List insight labels. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: project\_id, name, created\_at, updated\_at, insightsCount, screenAnnotationsCount. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[description]` | query | No | Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `include` | query | No | Comma-separated relationships. Allowed: insightsCount, screenAnnotationsCount. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[description] ```json { "type": "string" } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/insight-labels' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `InsightLabelResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "InsightLabelColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "color", "order", "created_at", "updated_at", "deleted_at" ], "title": "InsightLabelResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "project_id": null, "name": null, "color": null, "order": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-insights-insight # Get insight GET /insights/{insight}. Parameters, permissions, request and response schemas. `GET /insights/{insight}` Get insight. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `insight` | path | Yes | The insight ID | | `include` | query | No | Comma-separated relationships or counts. Allowed: ideasCount, experimentsCount, learningsCount, observationsCount, screenAnnotationsCount, audiences, experiments, ideas, learnings, observations, pages, screenAnnotations. | ### insight ```json { "type": "integer", "minimum": 1 } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/insights/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `InsightResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "research_collection_id": null, "insight_label_id": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_label": null, "name": null, "description": null, "created_at": null, "updated_at": null, "deleted_at": null, "has_ideas": true } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-insights # List insights GET /insights. Parameters, permissions, request and response schemas. `GET /insights` List insights. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project\_id, research\_collection\_id, user\_id, custom\_id, name, source. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[research_collection_id]` | query | No | Filter by research\_collection\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[user_id]` | query | No | Filter by user\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[custom_id]` | query | No | Filter by custom\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[source]` | query | No | Filter by source. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `include` | query | No | Comma-separated relationships. Allowed: audiences, experiments, ideas, learnings, observations, pages, screenAnnotations, ideasCount, experimentsCount, learningsCount, observationsCount, screenAnnotationsCount. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[research\_collection\_id] ```json { "type": "string" } ``` ### filter\[user\_id] ```json { "type": "string" } ``` ### filter\[custom\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[source] ```json { "type": "string" } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/insights' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `InsightResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "research_collection_id": null, "insight_label_id": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_label": null, "name": null, "description": null, "created_at": null, "updated_at": null, "deleted_at": null, "has_ideas": true } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-learnings-learning # Get learning GET /learnings/{learning}. Parameters, permissions, request and response schemas. `GET /learnings/{learning}` Get learning. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ---------- | -------- | -------- | -------------------------------------------------------------------------- | | `learning` | path | Yes | The learning ID | | `include` | query | No | Comma-separated relationships or counts. Allowed: insightsCount, insights. | ### learning ```json { "type": "integer", "minimum": 1 } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/learnings/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `LearningResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "confidence": { "type": [ "string", "null" ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "confidence", "learned_at", "created_at", "updated_at", "deleted_at" ], "title": "LearningResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "confidence": null, "learned_at": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-learnings # List learnings GET /learnings. Parameters, permissions, request and response schemas. `GET /learnings` List learnings. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project\_id, research\_collection\_id, user\_id, name, confidence, learned\_at, created\_at, updated\_at. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[research_collection_id]` | query | No | Filter by research\_collection\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[user_id]` | query | No | Filter by user\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[confidence]` | query | No | Filter by confidence. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `include` | query | No | Comma-separated relationships. Allowed: insights, insightsCount. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[research\_collection\_id] ```json { "type": "string" } ``` ### filter\[user\_id] ```json { "type": "string" } ``` ### filter\[confidence] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/learnings' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `LearningResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "confidence": { "type": [ "string", "null" ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "confidence", "learned_at", "created_at", "updated_at", "deleted_at" ], "title": "LearningResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "confidence": null, "learned_at": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-metrics-metric # Get metric GET /metrics/{metric}. Parameters, permissions, request and response schemas. `GET /metrics/{metric}` Get metric. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------- | -------- | -------- | ------------- | | `metric` | path | Yes | The metric ID | ### metric ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/metrics/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `MetricResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "description": null, "type": null, "winning_direction": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-metrics # List metrics GET /metrics. Parameters, permissions, request and response schemas. `GET /metrics` List metrics. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, name, winning\_direction, type, project\_id. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[winning_direction]` | query | No | Filter by winning\_direction. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[type]` | query | No | Filter by type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[winning\_direction] ```json { "type": "string" } ``` ### filter\[type] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/metrics' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `MetricResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "description": null, "type": null, "winning_direction": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-numbering-schemes # List numbering schemes GET /numbering-schemes. Parameters, permissions, request and response schemas. `GET /numbering-schemes` List numbering schemes. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/numbering-schemes' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string" }, "template": { "type": "string" }, "initial_number": { "type": "integer" }, "is_active": { "type": "boolean" }, "claims_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "entity_type": { "type": "string" }, "assignment_scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "entity_type", "assignment_scope_key", "project_id" ] } }, "sequence_states": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] }, "project_code": { "type": [ "string", "null" ] }, "next_number": { "type": "integer" } }, "required": [ "id", "scope_key", "project_id", "project_code", "next_number" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "scope", "template", "initial_number", "is_active", "claims_count", "assignments", "sequence_states", "created_at", "updated_at" ] } } }, "required": [ "data" ] } ``` ```json { "data": [ { "id": 101, "name": "Checkout delivery estimate", "scope": "example", "template": "example", "initial_number": 1, "is_active": true, "claims_count": "example", "assignments": [ { "id": 101, "entity_type": "example", "assignment_scope_key": "example", "project_id": null } ], "sequence_states": [ { "id": 101, "scope_key": "example", "project_id": null, "project_code": null, "next_number": 1 } ], "created_at": null, "updated_at": null } ] } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-observations-observation # Get observation GET /observations/{observation}. Parameters, permissions, request and response schemas. `GET /observations/{observation}` Get observation. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `observation` | path | Yes | The observation ID | | `include` | query | No | Comma-separated relationships or counts. Allowed: insightsCount, screenAnnotationsCount, pagesCount, insights, screenAnnotations, pages. | ### observation ```json { "type": "integer", "minimum": 1 } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/observations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ObservationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "evidence_kind": { "type": [ "string", "null" ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked": { "type": "boolean" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by": { "type": [ "integer", "null" ] }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_status": { "type": "string" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "source_type", "source_id", "source_item_key", "source_label", "evidence_kind", "evidence_payload", "confidence", "observed_at", "locked", "accepted_at", "accepted_by", "dismissed_at", "dismissed_by", "created_at", "updated_at", "deleted_at", "review_status" ], "title": "ObservationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-observations # List observations GET /observations. Parameters, permissions, request and response schemas. `GET /observations` List observations. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project\_id, research\_collection\_id, user\_id, name, source\_type, evidence\_kind, confidence, observed\_at, created\_at, updated\_at. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[research_collection_id]` | query | No | Filter by research\_collection\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[user_id]` | query | No | Filter by user\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[source_type]` | query | No | Filter by source\_type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[source_id]` | query | No | Filter by source\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[evidence_kind]` | query | No | Filter by evidence\_kind. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[confidence]` | query | No | Filter by confidence. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[locked]` | query | No | Filter by locked. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[review_status]` | query | No | Filter by review\_status. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[source_label]` | query | No | Filter by source\_label. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `include` | query | No | Comma-separated relationships. Allowed: insights, pages, screenAnnotations, insightsCount, pagesCount, screenAnnotationsCount. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[research\_collection\_id] ```json { "type": "string" } ``` ### filter\[user\_id] ```json { "type": "string" } ``` ### filter\[source\_type] ```json { "type": "string" } ``` ### filter\[source\_id] ```json { "type": "string" } ``` ### filter\[evidence\_kind] ```json { "type": "string" } ``` ### filter\[confidence] ```json { "type": "string" } ``` ### filter\[locked] ```json { "type": "string" } ``` ### filter\[review\_status] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[source\_label] ```json { "type": "string" } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/observations' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `ObservationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "evidence_kind": { "type": [ "string", "null" ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked": { "type": "boolean" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by": { "type": [ "integer", "null" ] }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_status": { "type": "string" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "source_type", "source_id", "source_item_key", "source_label", "evidence_kind", "evidence_payload", "confidence", "observed_at", "locked", "accepted_at", "accepted_by", "dismissed_at", "dismissed_by", "created_at", "updated_at", "deleted_at", "review_status" ], "title": "ObservationResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-pages-page # Get page GET /pages/{page}. Parameters, permissions, request and response schemas. `GET /pages/{page}` Get page. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | ---------------------------------------------------------------------------------------------- | | `page` | path | Yes | The page ID | | `include` | query | No | Comma-separated relationships or counts. Allowed: experimentsCount, ideasCount, insightsCount. | ### page ```json { "type": "integer", "minimum": 1 } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/pages/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `PageResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-pages # List pages GET /pages. Parameters, permissions, request and response schemas. `GET /pages` List pages. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: project\_id, name, created\_at, updated\_at, experimentsCount, ideasCount, insightsCount. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[description]` | query | No | Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `include` | query | No | Comma-separated relationships. Allowed: experimentsCount, ideasCount, insightsCount. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[description] ```json { "type": "string" } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/pages' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `PageResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-prio-models-prio-model # Get prio model GET /prio-models/{prio\_model}. Parameters, permissions, request and response schemas. `GET /prio-models/{prio_model}` Get prio model. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `prio_model` | path | Yes | The prio model ID | ### prio\_model ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/prio-models/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `PrioModelResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "default_config": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "key": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "select" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "default": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] } }, "required": [ "name", "key", "type" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "description", "default_config", "created_at", "updated_at" ], "title": "PrioModelResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] }, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-prio-models # List prio models GET /prio-models. Parameters, permissions, request and response schemas. `GET /prio-models` List prio models. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: name. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### sort ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/prio-models' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `PrioModelResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "default_config": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "key": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "select" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "default": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] } }, "required": [ "name", "key", "type" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "description", "default_config", "created_at", "updated_at" ], "title": "PrioModelResource" } } }, "required": [ "data" ] } ``` ```json { "data": [ { "id": 101, "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] }, "created_at": null, "updated_at": null } ] } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-projects-project # Get project GET /projects/{project}. Parameters, permissions, request and response schemas. `GET /projects/{project}` Get project. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------------ | | `project` | path | Yes | The project ID | | `include` | query | No | Include the project prioritization model with include=prio\_model. | ### project ```json { "type": "integer", "minimum": 1 } ``` ### include ```json { "type": "string", "enum": [ "prio_model" ] } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/projects/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ProjectResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "public_id": { "type": "string" }, "state": { "anyOf": [ { "type": "string", "enum": [ "active", "archived" ], "title": "ProjectState" }, { "type": "null" } ] }, "name": { "type": "string" }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "ProjectColor" }, { "type": "null" } ] }, "prio_model_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "public_id", "state", "name", "cover", "color", "prio_model_id", "created_at", "updated_at" ], "title": "ProjectResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-projects # List projects GET /projects. Parameters, permissions, request and response schemas. `GET /projects` List projects. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, state, name. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[state]` | query | No | Filter by state. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[state] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/projects' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `ProjectResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "public_id": { "type": "string" }, "state": { "anyOf": [ { "type": "string", "enum": [ "active", "archived" ], "title": "ProjectState" }, { "type": "null" } ] }, "name": { "type": "string" }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "ProjectColor" }, { "type": "null" } ] }, "prio_model_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "public_id", "state", "name", "cover", "color", "prio_model_id", "created_at", "updated_at" ], "title": "ProjectResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-research-collections-research-collection # Get research collection GET /research-collections/{research\_collection}. Parameters, permissions, request and response schemas. `GET /research-collections/{research_collection}` Get research collection. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------------------- | -------- | -------- | -------------------------- | | `research_collection` | path | Yes | The research collection ID | ### research\_collection ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/research-collections/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ResearchCollectionResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "cover", "created_at", "updated_at" ], "title": "ResearchCollectionResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-research-collections # List research collections GET /research-collections. Parameters, permissions, request and response schemas. `GET /research-collections` List research collections. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project\_id, name, created\_at, updated\_at. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[description]` | query | No | Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[description] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/research-collections' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `ResearchCollectionResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "cover", "created_at", "updated_at" ], "title": "ResearchCollectionResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-roadmap-annotations-roadmap-annotation # Get roadmap annotation GET /roadmap-annotations/{roadmap\_annotation}. Parameters, permissions, request and response schemas. `GET /roadmap-annotations/{roadmap_annotation}` Get roadmap annotation. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------------- | -------- | -------- | ------------------------- | | `roadmap_annotation` | path | Yes | The roadmap annotation ID | ### roadmap\_annotation ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/roadmap-annotations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `RoadmapAnnotationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "overlay", "marker" ], "title": "RoadmapAnnotationType" }, "annotation_type": { "type": "string" }, "label": { "type": "string" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "type", "annotation_type", "label", "start_date", "end_date", "notes", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "RoadmapAnnotationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z", "end_date": null, "notes": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-roadmap-annotations # List roadmap annotations GET /roadmap-annotations. Parameters, permissions, request and response schemas. `GET /roadmap-annotations` List roadmap annotations. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project\_id, type, annotation\_type, label, start\_date, end\_date, created\_at. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[type]` | query | No | Filter by type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[annotation_type]` | query | No | Filter by annotation\_type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[label]` | query | No | Filter by label. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[type] ```json { "type": "string" } ``` ### filter\[annotation\_type] ```json { "type": "string" } ``` ### filter\[label] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/roadmap-annotations' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `RoadmapAnnotationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "overlay", "marker" ], "title": "RoadmapAnnotationType" }, "annotation_type": { "type": "string" }, "label": { "type": "string" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "type", "annotation_type", "label", "start_date", "end_date", "notes", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "RoadmapAnnotationResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z", "end_date": null, "notes": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-screen-annotations-screen-annotation # Get screen annotation GET /screen-annotations/{screen\_annotation}. Parameters, permissions, request and response schemas. `GET /screen-annotations/{screen_annotation}` Get screen annotation. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------------------- | -------- | -------- | ------------------------ | | `screen_annotation` | path | Yes | The screen annotation ID | ### screen\_annotation ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/screen-annotations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ScreenAnnotationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "screen_id": { "type": "integer" }, "insight_label_id": { "type": [ "integer", "null" ] }, "note": { "type": [ "string", "null" ] }, "x": { "type": [ "integer", "null" ] }, "y": { "type": [ "integer", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "shape": { "type": "string" }, "metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "screen_id", "insight_label_id", "note", "x", "y", "width", "height", "shape", "metadata", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "ScreenAnnotationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "screen_id": 101, "insight_label_id": null, "note": null, "x": null, "y": null, "width": null, "height": null, "shape": "example", "metadata": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-screen-annotations # List screen annotations GET /screen-annotations. Parameters, permissions, request and response schemas. `GET /screen-annotations` List screen annotations. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project\_id, screen\_id, note, x, y, width, height, shape, user\_id. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[screen_id]` | query | No | Filter by screen\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[note]` | query | No | Filter by note. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[x]` | query | No | Filter by x. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[y]` | query | No | Filter by y. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[shape]` | query | No | Filter by shape. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[user_id]` | query | No | Filter by user\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[screen\_id] ```json { "type": "string" } ``` ### filter\[note] ```json { "type": "string" } ``` ### filter\[x] ```json { "type": "string" } ``` ### filter\[y] ```json { "type": "string" } ``` ### filter\[shape] ```json { "type": "string" } ``` ### filter\[user\_id] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/screen-annotations' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `ScreenAnnotationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "screen_id": { "type": "integer" }, "insight_label_id": { "type": [ "integer", "null" ] }, "note": { "type": [ "string", "null" ] }, "x": { "type": [ "integer", "null" ] }, "y": { "type": [ "integer", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "shape": { "type": "string" }, "metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "screen_id", "insight_label_id", "note", "x", "y", "width", "height", "shape", "metadata", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "ScreenAnnotationResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "project_id": 101, "screen_id": 101, "insight_label_id": null, "note": null, "x": null, "y": null, "width": null, "height": null, "shape": "example", "metadata": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-screens-screen # Get screen GET /screens/{screen}. Parameters, permissions, request and response schemas. `GET /screens/{screen}` Get screen. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | ---------------------------------------------------------------------------------------- | | `screen` | path | Yes | The screen ID | | `include` | query | No | Comma-separated relationships or counts. Allowed: audience, page, insights, annotations. | ### screen ```json { "type": "integer", "minimum": 1 } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/screens/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ScreenResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "audience_id": { "type": [ "integer", "null" ] }, "page_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "audience_id", "page_id", "name", "description", "image", "width", "height", "created_at", "updated_at", "deleted_at" ], "title": "ScreenResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "audience_id": null, "page_id": null, "name": null, "description": null, "image": null, "width": null, "height": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-screens # List screens GET /screens. Parameters, permissions, request and response schemas. `GET /screens` List screens. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project\_id, research\_collection\_id, audience\_id, page\_id, name, description. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[research_collection_id]` | query | No | Filter by research\_collection\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[audience_id]` | query | No | Filter by audience\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[page_id]` | query | No | Filter by page\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[description]` | query | No | Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `include` | query | No | Comma-separated relationships. Allowed: insightsCount. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[research\_collection\_id] ```json { "type": "string" } ``` ### filter\[audience\_id] ```json { "type": "string" } ``` ### filter\[page\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[description] ```json { "type": "string" } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/screens' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `ScreenResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "audience_id": { "type": [ "integer", "null" ] }, "page_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "audience_id", "page_id", "name", "description", "image", "width", "height", "created_at", "updated_at", "deleted_at" ], "title": "ScreenResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "project_id": 101, "research_collection_id": null, "audience_id": null, "page_id": null, "name": null, "description": null, "image": null, "width": null, "height": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-tags-tag # Get tag GET /tags/{tag}. Parameters, permissions, request and response schemas. `GET /tags/{tag}` Get tag. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ----- | -------- | -------- | ----------- | | `tag` | path | Yes | The tag ID | ### tag ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/tags/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `TagResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "generic", "page", "device", "insight-detail-type", "audience" ], "title": "TagType" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "type", "description", "created_at", "updated_at" ], "title": "TagResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "type": "generic", "description": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-tags # List tags GET /tags. Parameters, permissions, request and response schemas. `GET /tags` List tags. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, name, type. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[type]` | query | No | Filter by type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `include` | query | No | Comma-separated relationships. Allowed: experimentsCount, ideasCount, insightsCount. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[type] ```json { "type": "string" } ``` ### include ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/tags' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `TagResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "generic", "page", "device", "insight-detail-type", "audience" ], "title": "TagType" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "type", "description", "created_at", "updated_at" ], "title": "TagResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "type": "generic", "description": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-type-id-attachments # List attachments GET /{type}/{id}/attachments. Parameters, permissions, request and response schemas. `GET /{type}/{id}/attachments` List attachments. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `type` | path | Yes | Type. | | `id` | path | Yes | Id. | ### type ```json { "type": "string", "enum": [ "experiments", "ideas", "insights", "variations" ] } ``` ### id ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/experiments/101/attachments' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `AttachmentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "file_type": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "image", "document", "link" ], "title": "AttachmentType" }, "url": { "type": [ "string", "null" ] }, "attachable_type": { "type": "string" }, "attachable_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "file_type", "file_size", "type", "url", "attachable_type", "attachable_id", "created_at", "updated_at" ], "title": "AttachmentResource" } } }, "required": [ "data" ] } ``` ```json { "data": [ { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } ] } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-user # Get the authenticated user GET /user. Parameters, permissions, request and response schemas. `GET /user` Get the authenticated user. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/user' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `User` Content type: `application/json`. ```json { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_visited_team_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "avatar", "email", "timezone", "email_verified_at", "last_login_at", "last_visited_team_id", "created_at", "updated_at" ], "title": "User" } ``` ```json { "id": 101, "name": "Checkout delivery estimate", "avatar": null, "email": "alex@example.com", "timezone": null, "email_verified_at": null, "last_login_at": null, "last_visited_team_id": null, "created_at": null, "updated_at": null } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-variations-variation # Get variation GET /variations/{variation}. Parameters, permissions, request and response schemas. `GET /variations/{variation}` Get variation. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ----------- | -------- | -------- | ---------------- | | `variation` | path | Yes | The variation ID | ### variation ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/variations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `VariationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "name": { "type": "string" }, "traffic_percentage": { "type": "number" }, "traffic_locked": { "type": "boolean" }, "is_baseline": { "type": "boolean" }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "experiment_id", "name", "traffic_percentage", "traffic_locked", "is_baseline", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at" ], "title": "VariationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate", "traffic_percentage": 1, "traffic_locked": true, "is_baseline": true, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/get-variations # List variations GET /variations. Parameters, permissions, request and response schemas. `GET /variations` List variations. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } ``` ## Parameters | Name | Location | Required | Description | | ----------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `page[number]` | query | No | Page number, starting at 1. | | `page[size]` | query | No | Results per page. Values above the configured maximum are capped. | | `sort` | query | No | Comma-separated sort fields; prefix a field with - for descending order. Allowed: name, traffic\_percentage, is\_baseline. | | `filter[id]` | query | No | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[project_id]` | query | No | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[experiment_id]` | query | No | Filter by experiment\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[name]` | query | No | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | | `filter[is_baseline]` | query | No | Filter by is\_baseline. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. | ### page\[number] ```json { "type": "integer", "minimum": 1, "default": 1 } ``` ### page\[size] ```json { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } ``` ### sort ```json { "type": "string" } ``` ### filter\[id] ```json { "type": "string" } ``` ### filter\[project\_id] ```json { "type": "string" } ``` ### filter\[experiment\_id] ```json { "type": "string" } ``` ### filter\[name] ```json { "type": "string" } ``` ### filter\[is\_baseline] ```json { "type": "string" } ``` ## Example request ```bash curl --request GET 'https://api.example.test/api/variations' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `VariationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "name": { "type": "string" }, "traffic_percentage": { "type": "number" }, "traffic_locked": { "type": "boolean" }, "is_baseline": { "type": "boolean" }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "experiment_id", "name", "traffic_percentage", "traffic_locked", "is_baseline", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at" ], "title": "VariationResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } ``` ```json { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate", "traffic_percentage": 1, "traffic_locked": true, "is_baseline": true, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } ``` ### 400 Unsupported filter, sort, or include. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] } ``` ```json { "message": "Requested query option is not allowed." } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api # REST API reference The supported core data and reporting API, generated from the Laravel application. [Download OpenAPI](https://conversionlab.app/docs/openapi.json). Every endpoint below uses the existing runtime URL. Provider connection, import execution, AI generation, administration, and session endpoints are outside this public API contract. ## Activities - [List activities](https://conversionlab.app/docs/developer/api/get-activities) — `GET /activities` ## Attachments - [List attachments](https://conversionlab.app/docs/developer/api/get-attachments) — `GET /attachments` - [Create attachment](https://conversionlab.app/docs/developer/api/post-attachments) — `POST /attachments` - [Delete attachment](https://conversionlab.app/docs/developer/api/delete-attachments-attachment) — `DELETE /attachments/{attachment}` - [Get attachment](https://conversionlab.app/docs/developer/api/get-attachments-attachment) — `GET /attachments/{attachment}` - [Update attachment](https://conversionlab.app/docs/developer/api/patch-attachments-attachment) — `PATCH /attachments/{attachment}` - [Update attachment](https://conversionlab.app/docs/developer/api/put-attachments-attachment) — `PUT /attachments/{attachment}` - [List attachments](https://conversionlab.app/docs/developer/api/get-type-id-attachments) — `GET /{type}/{id}/attachments` ## Audiences - [List audiences](https://conversionlab.app/docs/developer/api/get-audiences) — `GET /audiences` - [Create audience](https://conversionlab.app/docs/developer/api/post-audiences) — `POST /audiences` - [Delete audience](https://conversionlab.app/docs/developer/api/delete-audiences-audience) — `DELETE /audiences/{audience}` - [Get audience](https://conversionlab.app/docs/developer/api/get-audiences-audience) — `GET /audiences/{audience}` - [Update audience](https://conversionlab.app/docs/developer/api/patch-audiences-audience) — `PATCH /audiences/{audience}` - [Update audience](https://conversionlab.app/docs/developer/api/put-audiences-audience) — `PUT /audiences/{audience}` ## Comments - [List comments](https://conversionlab.app/docs/developer/api/get-comments) — `GET /comments` - [Create comment](https://conversionlab.app/docs/developer/api/post-comments) — `POST /comments` - [Delete comment](https://conversionlab.app/docs/developer/api/delete-comments-comment) — `DELETE /comments/{comment}` - [Update comment](https://conversionlab.app/docs/developer/api/patch-comments-comment) — `PATCH /comments/{comment}` - [Update comment](https://conversionlab.app/docs/developer/api/put-comments-comment) — `PUT /comments/{comment}` ## Daily Briefs - [Get daily brief](https://conversionlab.app/docs/developer/api/get-daily-briefs-today) — `GET /daily-briefs/today` ## Experiment States - [List experiment states](https://conversionlab.app/docs/developer/api/get-experiment-states) — `GET /experiment-states` - [Create experiment state](https://conversionlab.app/docs/developer/api/post-experiment-states) — `POST /experiment-states` - [Reorder experiment states](https://conversionlab.app/docs/developer/api/put-experiment-states-order) — `PUT /experiment-states/order` - [Delete experiment state](https://conversionlab.app/docs/developer/api/delete-experiment-states-experiment-state) — `DELETE /experiment-states/{experiment_state}` - [Get experiment state](https://conversionlab.app/docs/developer/api/get-experiment-states-experiment-state) — `GET /experiment-states/{experiment_state}` - [Update experiment state](https://conversionlab.app/docs/developer/api/patch-experiment-states-experiment-state) — `PATCH /experiment-states/{experiment_state}` - [Update experiment state](https://conversionlab.app/docs/developer/api/put-experiment-states-experiment-state) — `PUT /experiment-states/{experiment_state}` ## Experiments - [List experiments](https://conversionlab.app/docs/developer/api/get-experiments) — `GET /experiments` - [Create experiment](https://conversionlab.app/docs/developer/api/post-experiments) — `POST /experiments` - [Apply a bulk action to experiments](https://conversionlab.app/docs/developer/api/post-experiments-bulk) — `POST /experiments/bulk` - [Delete experiment](https://conversionlab.app/docs/developer/api/delete-experiments-experiment) — `DELETE /experiments/{experiment}` - [Get experiment](https://conversionlab.app/docs/developer/api/get-experiments-experiment) — `GET /experiments/{experiment}` - [Update experiment](https://conversionlab.app/docs/developer/api/patch-experiments-experiment) — `PATCH /experiments/{experiment}` - [Update experiment](https://conversionlab.app/docs/developer/api/put-experiments-experiment) — `PUT /experiments/{experiment}` - [List experiment approvals](https://conversionlab.app/docs/developer/api/get-experiments-experiment-approvals) — `GET /experiments/{experiment}/approvals` - [Record experiment approvals](https://conversionlab.app/docs/developer/api/post-experiments-experiment-approvals) — `POST /experiments/{experiment}/approvals` - [Distribute traffic for experiment](https://conversionlab.app/docs/developer/api/post-experiments-experiment-distribute-traffic) — `POST /experiments/{experiment}/distribute-traffic` - [Get the result report for experiment](https://conversionlab.app/docs/developer/api/get-experiments-experiment-summary) — `GET /experiments/{experiment}/summary` - [Get result time series for experiment](https://conversionlab.app/docs/developer/api/get-experiments-experiment-timeseries) — `GET /experiments/{experiment}/timeseries` ## Forms - [List forms](https://conversionlab.app/docs/developer/api/get-forms) — `GET /forms` - [Create form](https://conversionlab.app/docs/developer/api/post-forms) — `POST /forms` - [Apply a bulk action to forms](https://conversionlab.app/docs/developer/api/post-forms-bulk) — `POST /forms/bulk` - [Duplicate form](https://conversionlab.app/docs/developer/api/post-forms-duplicate) — `POST /forms/duplicate` - [Delete form](https://conversionlab.app/docs/developer/api/delete-forms-form) — `DELETE /forms/{form}` - [Get form](https://conversionlab.app/docs/developer/api/get-forms-form) — `GET /forms/{form}` - [Update form](https://conversionlab.app/docs/developer/api/patch-forms-form) — `PATCH /forms/{form}` - [Update form](https://conversionlab.app/docs/developer/api/put-forms-form) — `PUT /forms/{form}` - [Get form](https://conversionlab.app/docs/developer/api/get-forms-form-response-summary) — `GET /forms/{form}/response-summary` - [Reset survey responses](https://conversionlab.app/docs/developer/api/delete-forms-form-responses) — `DELETE /forms/{form}/responses` - [List forms](https://conversionlab.app/docs/developer/api/get-forms-form-responses) — `GET /forms/{form}/responses` - [Export responses for form](https://conversionlab.app/docs/developer/api/get-forms-form-responses-export) — `GET /forms/{form}/responses/export` ## Idea States - [List idea states](https://conversionlab.app/docs/developer/api/get-idea-states) — `GET /idea-states` - [Create idea state](https://conversionlab.app/docs/developer/api/post-idea-states) — `POST /idea-states` - [Reorder idea states](https://conversionlab.app/docs/developer/api/put-idea-states-order) — `PUT /idea-states/order` - [Delete idea state](https://conversionlab.app/docs/developer/api/delete-idea-states-idea-state) — `DELETE /idea-states/{idea_state}` - [Get idea state](https://conversionlab.app/docs/developer/api/get-idea-states-idea-state) — `GET /idea-states/{idea_state}` - [Update idea state](https://conversionlab.app/docs/developer/api/patch-idea-states-idea-state) — `PATCH /idea-states/{idea_state}` - [Update idea state](https://conversionlab.app/docs/developer/api/put-idea-states-idea-state) — `PUT /idea-states/{idea_state}` ## Ideas - [List ideas](https://conversionlab.app/docs/developer/api/get-ideas) — `GET /ideas` - [Create idea](https://conversionlab.app/docs/developer/api/post-ideas) — `POST /ideas` - [Apply a bulk action to ideas](https://conversionlab.app/docs/developer/api/post-ideas-bulk) — `POST /ideas/bulk` - [Delete idea](https://conversionlab.app/docs/developer/api/delete-ideas-idea) — `DELETE /ideas/{idea}` - [Get idea](https://conversionlab.app/docs/developer/api/get-ideas-idea) — `GET /ideas/{idea}` - [Update idea](https://conversionlab.app/docs/developer/api/patch-ideas-idea) — `PATCH /ideas/{idea}` - [Update idea](https://conversionlab.app/docs/developer/api/put-ideas-idea) — `PUT /ideas/{idea}` ## Insight Labels - [List insight labels](https://conversionlab.app/docs/developer/api/get-insight-labels) — `GET /insight-labels` - [Create insight label](https://conversionlab.app/docs/developer/api/post-insight-labels) — `POST /insight-labels` - [Delete insight label](https://conversionlab.app/docs/developer/api/delete-insight-labels-insight-label) — `DELETE /insight-labels/{insight_label}` - [Get insight label](https://conversionlab.app/docs/developer/api/get-insight-labels-insight-label) — `GET /insight-labels/{insight_label}` - [Update insight label](https://conversionlab.app/docs/developer/api/patch-insight-labels-insight-label) — `PATCH /insight-labels/{insight_label}` - [Update insight label](https://conversionlab.app/docs/developer/api/put-insight-labels-insight-label) — `PUT /insight-labels/{insight_label}` ## Insights - [List insights](https://conversionlab.app/docs/developer/api/get-insights) — `GET /insights` - [Create insight](https://conversionlab.app/docs/developer/api/post-insights) — `POST /insights` - [Apply a bulk action to insights](https://conversionlab.app/docs/developer/api/post-insights-bulk) — `POST /insights/bulk` - [Delete insight](https://conversionlab.app/docs/developer/api/delete-insights-insight) — `DELETE /insights/{insight}` - [Get insight](https://conversionlab.app/docs/developer/api/get-insights-insight) — `GET /insights/{insight}` - [Update insight](https://conversionlab.app/docs/developer/api/patch-insights-insight) — `PATCH /insights/{insight}` - [Update insight](https://conversionlab.app/docs/developer/api/put-insights-insight) — `PUT /insights/{insight}` ## Learnings - [List learnings](https://conversionlab.app/docs/developer/api/get-learnings) — `GET /learnings` - [Create learning](https://conversionlab.app/docs/developer/api/post-learnings) — `POST /learnings` - [Apply a bulk action to learnings](https://conversionlab.app/docs/developer/api/post-learnings-bulk) — `POST /learnings/bulk` - [Delete learning](https://conversionlab.app/docs/developer/api/delete-learnings-learning) — `DELETE /learnings/{learning}` - [Get learning](https://conversionlab.app/docs/developer/api/get-learnings-learning) — `GET /learnings/{learning}` - [Update learning](https://conversionlab.app/docs/developer/api/patch-learnings-learning) — `PATCH /learnings/{learning}` - [Update learning](https://conversionlab.app/docs/developer/api/put-learnings-learning) — `PUT /learnings/{learning}` ## Metrics - [List metrics](https://conversionlab.app/docs/developer/api/get-metrics) — `GET /metrics` - [Create metric](https://conversionlab.app/docs/developer/api/post-metrics) — `POST /metrics` - [Delete metric](https://conversionlab.app/docs/developer/api/delete-metrics-metric) — `DELETE /metrics/{metric}` - [Get metric](https://conversionlab.app/docs/developer/api/get-metrics-metric) — `GET /metrics/{metric}` - [Update metric](https://conversionlab.app/docs/developer/api/patch-metrics-metric) — `PATCH /metrics/{metric}` - [Update metric](https://conversionlab.app/docs/developer/api/put-metrics-metric) — `PUT /metrics/{metric}` ## Numbering Schemes - [List numbering schemes](https://conversionlab.app/docs/developer/api/get-numbering-schemes) — `GET /numbering-schemes` - [Create numbering scheme](https://conversionlab.app/docs/developer/api/post-numbering-schemes) — `POST /numbering-schemes` - [Preview numbering scheme](https://conversionlab.app/docs/developer/api/post-numbering-schemes-preview) — `POST /numbering-schemes/preview` - [Update numbering scheme](https://conversionlab.app/docs/developer/api/patch-numbering-schemes-numberingscheme) — `PATCH /numbering-schemes/{numberingScheme}` - [Update numbering scheme](https://conversionlab.app/docs/developer/api/put-numbering-schemes-numberingscheme) — `PUT /numbering-schemes/{numberingScheme}` - [Backfill identifiers using numbering scheme](https://conversionlab.app/docs/developer/api/post-numbering-schemes-numberingscheme-backfill) — `POST /numbering-schemes/{numberingScheme}/backfill` ## Observations - [List observations](https://conversionlab.app/docs/developer/api/get-observations) — `GET /observations` - [Create observation](https://conversionlab.app/docs/developer/api/post-observations) — `POST /observations` - [Apply a bulk action to observations](https://conversionlab.app/docs/developer/api/post-observations-bulk) — `POST /observations/bulk` - [Delete observation](https://conversionlab.app/docs/developer/api/delete-observations-observation) — `DELETE /observations/{observation}` - [Get observation](https://conversionlab.app/docs/developer/api/get-observations-observation) — `GET /observations/{observation}` - [Update observation](https://conversionlab.app/docs/developer/api/patch-observations-observation) — `PATCH /observations/{observation}` - [Update observation](https://conversionlab.app/docs/developer/api/put-observations-observation) — `PUT /observations/{observation}` - [Accept observation](https://conversionlab.app/docs/developer/api/post-observations-observation-accept) — `POST /observations/{observation}/accept` - [Dismiss observation](https://conversionlab.app/docs/developer/api/post-observations-observation-dismiss) — `POST /observations/{observation}/dismiss` - [Permanently delete an archived observation](https://conversionlab.app/docs/developer/api/delete-observations-observation-force) — `DELETE /observations/{observation}/force` - [Restore an archived observation](https://conversionlab.app/docs/developer/api/post-observations-observation-restore) — `POST /observations/{observation}/restore` - [Restore a dismissed observation](https://conversionlab.app/docs/developer/api/post-observations-observation-restore-dismissal) — `POST /observations/{observation}/restore-dismissal` ## Pages - [List pages](https://conversionlab.app/docs/developer/api/get-pages) — `GET /pages` - [Create page](https://conversionlab.app/docs/developer/api/post-pages) — `POST /pages` - [Delete page](https://conversionlab.app/docs/developer/api/delete-pages-page) — `DELETE /pages/{page}` - [Get page](https://conversionlab.app/docs/developer/api/get-pages-page) — `GET /pages/{page}` - [Update page](https://conversionlab.app/docs/developer/api/patch-pages-page) — `PATCH /pages/{page}` - [Update page](https://conversionlab.app/docs/developer/api/put-pages-page) — `PUT /pages/{page}` ## Prio Models - [List prio models](https://conversionlab.app/docs/developer/api/get-prio-models) — `GET /prio-models` - [Create prio model](https://conversionlab.app/docs/developer/api/post-prio-models) — `POST /prio-models` - [Validate the formula for prio model](https://conversionlab.app/docs/developer/api/post-prio-models-validate-formula) — `POST /prio-models/validate-formula` - [Recalculate priorities with prio model](https://conversionlab.app/docs/developer/api/post-prio-models-id-recalculate) — `POST /prio-models/{id}/recalculate` - [Delete prio model](https://conversionlab.app/docs/developer/api/delete-prio-models-prio-model) — `DELETE /prio-models/{prio_model}` - [Get prio model](https://conversionlab.app/docs/developer/api/get-prio-models-prio-model) — `GET /prio-models/{prio_model}` - [Update prio model](https://conversionlab.app/docs/developer/api/patch-prio-models-prio-model) — `PATCH /prio-models/{prio_model}` - [Update prio model](https://conversionlab.app/docs/developer/api/put-prio-models-prio-model) — `PUT /prio-models/{prio_model}` ## Projects - [List projects](https://conversionlab.app/docs/developer/api/get-projects) — `GET /projects` - [Create project](https://conversionlab.app/docs/developer/api/post-projects) — `POST /projects` - [Delete project](https://conversionlab.app/docs/developer/api/delete-projects-project) — `DELETE /projects/{project}` - [Get project](https://conversionlab.app/docs/developer/api/get-projects-project) — `GET /projects/{project}` - [Update project](https://conversionlab.app/docs/developer/api/patch-projects-project) — `PATCH /projects/{project}` - [Update project](https://conversionlab.app/docs/developer/api/post-projects-project) — `POST /projects/{project}` - [Update project](https://conversionlab.app/docs/developer/api/put-projects-project) — `PUT /projects/{project}` ## Research Collections - [List research collections](https://conversionlab.app/docs/developer/api/get-research-collections) — `GET /research-collections` - [Create research collection](https://conversionlab.app/docs/developer/api/post-research-collections) — `POST /research-collections` - [Delete research collection](https://conversionlab.app/docs/developer/api/delete-research-collections-research-collection) — `DELETE /research-collections/{research_collection}` - [Get research collection](https://conversionlab.app/docs/developer/api/get-research-collections-research-collection) — `GET /research-collections/{research_collection}` - [Update research collection](https://conversionlab.app/docs/developer/api/patch-research-collections-research-collection) — `PATCH /research-collections/{research_collection}` - [Update research collection](https://conversionlab.app/docs/developer/api/post-research-collections-research-collection) — `POST /research-collections/{research_collection}` - [Update research collection](https://conversionlab.app/docs/developer/api/put-research-collections-research-collection) — `PUT /research-collections/{research_collection}` ## Roadmap Annotations - [List roadmap annotations](https://conversionlab.app/docs/developer/api/get-roadmap-annotations) — `GET /roadmap-annotations` - [Create roadmap annotation](https://conversionlab.app/docs/developer/api/post-roadmap-annotations) — `POST /roadmap-annotations` - [Delete roadmap annotation](https://conversionlab.app/docs/developer/api/delete-roadmap-annotations-roadmap-annotation) — `DELETE /roadmap-annotations/{roadmap_annotation}` - [Get roadmap annotation](https://conversionlab.app/docs/developer/api/get-roadmap-annotations-roadmap-annotation) — `GET /roadmap-annotations/{roadmap_annotation}` - [Update roadmap annotation](https://conversionlab.app/docs/developer/api/patch-roadmap-annotations-roadmap-annotation) — `PATCH /roadmap-annotations/{roadmap_annotation}` - [Update roadmap annotation](https://conversionlab.app/docs/developer/api/put-roadmap-annotations-roadmap-annotation) — `PUT /roadmap-annotations/{roadmap_annotation}` ## Screen Annotations - [List screen annotations](https://conversionlab.app/docs/developer/api/get-screen-annotations) — `GET /screen-annotations` - [Create screen annotation](https://conversionlab.app/docs/developer/api/post-screen-annotations) — `POST /screen-annotations` - [Delete screen annotation](https://conversionlab.app/docs/developer/api/delete-screen-annotations-screen-annotation) — `DELETE /screen-annotations/{screen_annotation}` - [Get screen annotation](https://conversionlab.app/docs/developer/api/get-screen-annotations-screen-annotation) — `GET /screen-annotations/{screen_annotation}` - [Update screen annotation](https://conversionlab.app/docs/developer/api/patch-screen-annotations-screen-annotation) — `PATCH /screen-annotations/{screen_annotation}` - [Update screen annotation](https://conversionlab.app/docs/developer/api/put-screen-annotations-screen-annotation) — `PUT /screen-annotations/{screen_annotation}` ## Screens - [List screens](https://conversionlab.app/docs/developer/api/get-screens) — `GET /screens` - [Create screen](https://conversionlab.app/docs/developer/api/post-screens) — `POST /screens` - [Delete screen](https://conversionlab.app/docs/developer/api/delete-screens-screen) — `DELETE /screens/{screen}` - [Get screen](https://conversionlab.app/docs/developer/api/get-screens-screen) — `GET /screens/{screen}` - [Update screen](https://conversionlab.app/docs/developer/api/patch-screens-screen) — `PATCH /screens/{screen}` - [Update screen](https://conversionlab.app/docs/developer/api/put-screens-screen) — `PUT /screens/{screen}` ## Tags - [List tags](https://conversionlab.app/docs/developer/api/get-tags) — `GET /tags` - [Create tag](https://conversionlab.app/docs/developer/api/post-tags) — `POST /tags` - [Delete tag](https://conversionlab.app/docs/developer/api/delete-tags-tag) — `DELETE /tags/{tag}` - [Get tag](https://conversionlab.app/docs/developer/api/get-tags-tag) — `GET /tags/{tag}` - [Update tag](https://conversionlab.app/docs/developer/api/patch-tags-tag) — `PATCH /tags/{tag}` - [Update tag](https://conversionlab.app/docs/developer/api/put-tags-tag) — `PUT /tags/{tag}` ## User - [Get the authenticated user](https://conversionlab.app/docs/developer/api/get-user) — `GET /user` ## Variations - [List variations](https://conversionlab.app/docs/developer/api/get-variations) — `GET /variations` - [Create variation](https://conversionlab.app/docs/developer/api/post-variations) — `POST /variations` - [Delete variation](https://conversionlab.app/docs/developer/api/delete-variations-variation) — `DELETE /variations/{variation}` - [Get variation](https://conversionlab.app/docs/developer/api/get-variations-variation) — `GET /variations/{variation}` - [Update variation](https://conversionlab.app/docs/developer/api/patch-variations-variation) — `PATCH /variations/{variation}` - [Update variation](https://conversionlab.app/docs/developer/api/put-variations-variation) — `PUT /variations/{variation}` --- Source: https://conversionlab.app/docs/developer/api/patch-attachments-attachment # Update attachment PATCH /attachments/{attachment}. Parameters, permissions, request and response schemas. `PATCH /attachments/{attachment}` Update attachment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `attachment` | path | Yes | The attachment ID | ### attachment ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 } }, "title": "UpdateAttachmentRequest" } ``` ```json { "name": "Checkout delivery estimate" } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/attachments/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `AttachmentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "file_type": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "image", "document", "link" ], "title": "AttachmentType" }, "url": { "type": [ "string", "null" ] }, "attachable_type": { "type": "string" }, "attachable_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "file_type", "file_size", "type", "url", "attachable_type", "attachable_id", "created_at", "updated_at" ], "title": "AttachmentResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-audiences-audience # Update audience PATCH /audiences/{audience}. Parameters, permissions, request and response schemas. `PATCH /audiences/{audience}` Update audience. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ---------- | -------- | -------- | --------------- | | `audience` | path | Yes | The audience ID | ### audience ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 } }, "title": "UpdateAudienceRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/audiences/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `AudienceResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-comments-comment # Update comment PATCH /comments/{comment}. Parameters, permissions, request and response schemas. `PATCH /comments/{comment}` Update comment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | -------------- | | `comment` | path | Yes | The comment ID | ### comment ```json { "type": "integer", "minimum": 1 } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "body": { "type": "string", "maxLength": 5000 } }, "required": [ "body" ], "title": "UpdateCommentRequest" } ``` ```json { "body": "example" } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/comments/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"body":"example"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `CommentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "body": { "type": "string" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "seat_type": { "type": [ "string", "null" ] }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "email", "role", "seat_type", "email_verified_at", "created_at", "updated_at", "last_login_at" ], "title": "UserResource" }, { "type": "null" } ] }, "user_id": { "type": [ "integer", "null" ] }, "parent_id": { "type": [ "integer", "null" ] }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/CommentResource" } }, "is_approved": { "type": "boolean" }, "commentable_type": { "type": "string" }, "commentable_id": { "type": "integer" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "body", "user_id", "parent_id", "is_approved", "commentable_type", "commentable_id", "can_edit", "can_delete", "created_at", "updated_at" ], "title": "CommentResource" }, { "type": "object", "required": [ "user" ] } ] } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "body": "example", "user": null, "user_id": null, "parent_id": null, "is_approved": true, "commentable_type": "example", "commentable_id": 101, "can_edit": true, "can_delete": true, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-experiment-states-experiment-state # Update experiment state PATCH /experiment-states/{experiment\_state}. Parameters, permissions, request and response schemas. `PATCH /experiment-states/{experiment_state}` Update experiment state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------------ | -------- | -------- | ----------------------- | | `experiment_state` | path | Yes | The experiment state ID | ### experiment\_state ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "category": { "type": "string", "enum": [ "draft", "live", "paused", "finished", "archived" ], "title": "ExperimentStateCategory" }, "order": { "type": "integer", "minimum": 0 } }, "title": "UpdateExperimentStateRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/experiment-states/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ExperimentStateResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "category": { "anyOf": [ { "type": "string", "enum": [ "draft", "live", "paused", "finished", "archived" ], "title": "ExperimentStateCategory" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "category", "order", "created_at", "updated_at" ], "title": "ExperimentStateResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "description": null, "category": null, "order": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-experiments-experiment # Update experiment PATCH /experiments/{experiment}. Parameters, permissions, request and response schemas. `PATCH /experiments/{experiment}` Update experiment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `experiment` | path | Yes | The experiment ID | ### experiment ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, "state_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "source": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": "integer" }, "project_id": { "type": "integer" }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "idea_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "primary_metric_id": { "type": "integer" }, "secondary_metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "uniqueItems": true }, "guardrail_metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "uniqueItems": true }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" } }, "title": "UpdateExperimentRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/experiments/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ExperimentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-forms-form # Update form PATCH /forms/{form}. Parameters, permissions, request and response schemas. `PATCH /forms/{form}` Update form. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `form` | path | Yes | The form ID | ### form ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "widget", "inline", "link" ], "title": "FormType" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "FormStatus" }, "project_id": { "type": "integer" }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string", "maxLength": 500 }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" } }, "required": [ "type", "title" ] } } } } } }, "title": "UpdateFormRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/forms/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `FormResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "widget", "inline", "link" ], "title": "FormType" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "FormStatus" }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "title", "description", "order", "created_at", "updated_at" ], "title": "FormStepResource" } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "responses_count": { "type": "integer" }, "submitted_responses_count": { "type": "integer", "minimum": 0 }, "partial_responses_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "public_id", "project_id", "name", "description", "type", "status", "settings", "created_at", "updated_at" ], "title": "FormResource" }, { "type": "object", "required": [ "steps" ] } ] } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "steps": [ { "id": 101, "form_id": 101, "title": null, "description": null, "order": 1, "created_at": null, "updated_at": null } ], "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-idea-states-idea-state # Update idea state PATCH /idea-states/{idea\_state}. Parameters, permissions, request and response schemas. `PATCH /idea-states/{idea_state}` Update idea state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `idea_state` | path | Yes | The idea state ID | ### idea\_state ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "color": { "type": [ "string", "null" ], "maxLength": 255 }, "order": { "type": [ "integer", "null" ], "minimum": 0 } }, "title": "UpdateIdeaStateRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/idea-states/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `IdeaStateResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "description": null, "color": null, "order": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-ideas-idea # Update idea PATCH /ideas/{idea}. Parameters, permissions, request and response schemas. `PATCH /ideas/{idea}` Update idea. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `idea` | path | Yes | The idea ID | ### idea ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "source": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "project_id": { "type": "integer" }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "experiment_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "priority_values": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] } }, "title": "UpdateIdeaRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/ideas/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `IdeaResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "audit", "insight", "experiment", "form", "api" ], "title": "IdeaSourceType" }, { "type": "null" } ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_name": { "type": [ "string", "null" ] }, "priority_values": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_score": { "type": [ "number", "null" ] }, "priority_details": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_calculated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" } }, "experiments_count": { "type": "integer" }, "insights_count": { "type": "integer" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "project_id", "state_id", "name", "description", "hypothesis", "user_id", "source", "source_id", "source_item_key", "source_name", "priority_values", "priority_score", "priority_details", "priority_calculated_at", "created_at", "updated_at" ], "title": "IdeaResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "project_id": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_name": null, "priority_values": null, "priority_score": null, "priority_details": null, "priority_calculated_at": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-insight-labels-insight-label # Update insight label PATCH /insight-labels/{insight\_label}. Parameters, permissions, request and response schemas. `PATCH /insight-labels/{insight_label}` Update insight label. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------------- | -------- | -------- | -------------------- | | `insight_label` | path | Yes | The insight label ID | ### insight\_label ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "InsightLabelColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] } }, "title": "UpdateInsightLabelRequest" } ``` ```json { "project_id": 101, "name": null } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/insight-labels/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `InsightLabelResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "InsightLabelColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "color", "order", "created_at", "updated_at", "deleted_at" ], "title": "InsightLabelResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "color": null, "order": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-insights-insight # Update insight PATCH /insights/{insight}. Parameters, permissions, request and response schemas. `PATCH /insights/{insight}` Update insight. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | -------------- | | `insight` | path | Yes | The insight ID | ### insight ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "source": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "experiment_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "idea_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "observation_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "learning_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "screen_annotations": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } } }, "title": "UpdateInsightRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/insights/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `InsightResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "research_collection_id": null, "insight_label_id": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_label": null, "name": null, "description": null, "created_at": null, "updated_at": null, "deleted_at": null, "has_ideas": true } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-learnings-learning # Update learning PATCH /learnings/{learning}. Parameters, permissions, request and response schemas. `PATCH /learnings/{learning}` Update learning. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ---------- | -------- | -------- | --------------- | | `learning` | path | Yes | The learning ID | ### learning ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "title": "UpdateLearningRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/learnings/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `LearningResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "confidence": { "type": [ "string", "null" ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "confidence", "learned_at", "created_at", "updated_at", "deleted_at" ], "title": "LearningResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "confidence": null, "learned_at": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-metrics-metric # Update metric PATCH /metrics/{metric}. Parameters, permissions, request and response schemas. `PATCH /metrics/{metric}` Update metric. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | -------- | -------- | -------- | ------------- | | `metric` | path | Yes | The metric ID | ### metric ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "winning_direction": { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, "type": { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" } }, "title": "UpdateMetricRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/metrics/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `MetricResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "description": null, "type": null, "winning_direction": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-numbering-schemes-numberingscheme # Update numbering scheme PATCH /numbering-schemes/{numberingScheme}. Parameters, permissions, request and response schemas. `PATCH /numbering-schemes/{numberingScheme}` Update numbering scheme. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ----------------- | -------- | -------- | ----------------------- | | `numberingScheme` | path | Yes | The numbering scheme ID | ### numberingScheme ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "scope": { "type": "string", "enum": [ "team", "project" ] }, "template": { "type": "string", "maxLength": 120, "description": "Identifier template, for example EXP-{number:000}. Project-scoped templates may include {project_code}." }, "initial_number": { "type": "integer", "minimum": 1 }, "is_active": { "type": "boolean" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "experiments", "ideas", "insights" ] }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "entity_type" ] } } }, "example": { "name": "Experiment IDs", "scope": "team", "template": "EXP-{number:000}", "initial_number": 1, "assignments": [ { "entity_type": "experiments" } ] } } ``` ```json { "name": "Experiment IDs", "scope": "team", "template": "EXP-{number:000}", "initial_number": 1, "assignments": [ { "entity_type": "experiments" } ] } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/numbering-schemes/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Experiment IDs","scope":"team","template":"EXP-{number:000}","initial_number":1,"assignments":[{"entity_type":"experiments"}]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string" }, "template": { "type": "string" }, "initial_number": { "type": "integer" }, "is_active": { "type": "boolean" }, "claims_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "entity_type": { "type": "string" }, "assignment_scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "entity_type", "assignment_scope_key", "project_id" ] } }, "sequence_states": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] }, "project_code": { "type": [ "string", "null" ] }, "next_number": { "type": "integer" } }, "required": [ "id", "scope_key", "project_id", "project_code", "next_number" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "scope", "template", "initial_number", "is_active", "claims_count", "assignments", "sequence_states", "created_at", "updated_at" ] } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "name": "Checkout delivery estimate", "scope": "example", "template": "example", "initial_number": 1, "is_active": true, "claims_count": "example", "assignments": [ { "id": 101, "entity_type": "example", "assignment_scope_key": "example", "project_id": null } ], "sequence_states": [ { "id": 101, "scope_key": "example", "project_id": null, "project_code": null, "next_number": 1 } ], "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-observations-observation # Update observation PATCH /observations/{observation}. Parameters, permissions, request and response schemas. `PATCH /observations/{observation}` Update observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------- | -------- | -------- | ------------------ | | `observation` | path | Yes | The observation ID | ### observation ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "source_type": { "type": [ "string", "null" ], "enum": [ "manual", "audit", "experiment", "survey", "screen", "import", "external_research", null ] }, "source_id": { "type": [ "integer", "null" ], "minimum": 1 }, "source_item_key": { "type": [ "string", "null" ], "maxLength": 255 }, "source_label": { "type": [ "string", "null" ], "maxLength": 255 }, "evidence_kind": { "type": [ "string", "null" ], "enum": [ "screenshot_region", "quote", "metric_result", "page_text", "manual_note", "audit_observation", null ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "screen_annotation_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "title": "UpdateObservationRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/observations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ObservationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "evidence_kind": { "type": [ "string", "null" ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked": { "type": "boolean" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by": { "type": [ "integer", "null" ] }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_status": { "type": "string" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "source_type", "source_id", "source_item_key", "source_label", "evidence_kind", "evidence_payload", "confidence", "observed_at", "locked", "accepted_at", "accepted_by", "dismissed_at", "dismissed_by", "created_at", "updated_at", "deleted_at", "review_status" ], "title": "ObservationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-pages-page # Update page PATCH /pages/{page}. Parameters, permissions, request and response schemas. `PATCH /pages/{page}` Update page. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `page` | path | Yes | The page ID | ### page ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] } }, "title": "UpdatePageRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/pages/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `PageResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-prio-models-prio-model # Update prio model PATCH /prio-models/{prio\_model}. Parameters, permissions, request and response schemas. `PATCH /prio-models/{prio_model}` Update prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `prio_model` | path | Yes | The prio model ID | ### prio\_model ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "default_config": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "key": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "select" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "default": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] } }, "required": [ "name", "key", "type" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ] } }, "required": [ "name", "default_config" ], "title": "UpdatePrioModelRequest" }, { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "string" } } } ] } ``` ```json { "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] } } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/prio-models/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"default_config":{"formula":"impact * confidence / effort","inputs":[{"name":"Checkout delivery estimate","key":"example","description":null,"type":"number"}]}}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `PrioModelResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "default_config": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "key": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "select" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "default": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] } }, "required": [ "name", "key", "type" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "description", "default_config", "created_at", "updated_at" ], "title": "PrioModelResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] }, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-projects-project # Update project PATCH /projects/{project}. Parameters, permissions, request and response schemas. `PATCH /projects/{project}` Update project. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | -------------- | | `project` | path | Yes | The project ID | ### project ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### multipart/form-data ```json { "type": "object", "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "active", "archived" ], "title": "ProjectState" }, { "type": "null" } ] }, "name": { "type": "string", "maxLength": 255, "description": "Must be unique among projects in this Team, excluding the project being updated." }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 1024 kilobytes." }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "ProjectColor" }, { "type": "null" } ] }, "prio_model_id": { "type": [ "integer", "null" ] } }, "title": "UpdateProjectRequest" } ``` ```json { "name": "Checkout delivery estimate" } ``` ## Example request For file fields, replace the synthetic local filename with an existing file of the documented type and size. Let curl set the multipart boundary. ```bash curl --request PATCH 'https://api.example.test/api/projects/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --form-string 'name=Checkout delivery estimate' \ --form 'cover=@./screenshot.png' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ProjectResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "public_id": { "type": "string" }, "state": { "anyOf": [ { "type": "string", "enum": [ "active", "archived" ], "title": "ProjectState" }, { "type": "null" } ] }, "name": { "type": "string" }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "ProjectColor" }, { "type": "null" } ] }, "prio_model_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "public_id", "state", "name", "cover", "color", "prio_model_id", "created_at", "updated_at" ], "title": "ProjectResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-research-collections-research-collection # Update research collection PATCH /research-collections/{research\_collection}. Parameters, permissions, request and response schemas. `PATCH /research-collections/{research_collection}` Update research collection. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------------------- | -------- | -------- | -------------------------- | | `research_collection` | path | Yes | The research collection ID | ### research\_collection ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### multipart/form-data ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 1024 kilobytes." } }, "title": "UpdateResearchCollectionRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request For file fields, replace the synthetic local filename with an existing file of the documented type and size. Let curl set the multipart boundary. ```bash curl --request PATCH 'https://api.example.test/api/research-collections/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --form-string 'project_id=101' \ --form-string 'name=Checkout delivery estimate' \ --form 'cover=@./screenshot.png' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ResearchCollectionResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "cover", "created_at", "updated_at" ], "title": "ResearchCollectionResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` ### 500 The request failed. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "Error uploading file" } }, "required": [ "error" ] } ``` ```json { "error": "Error uploading file" } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-roadmap-annotations-roadmap-annotation # Update roadmap annotation PATCH /roadmap-annotations/{roadmap\_annotation}. Parameters, permissions, request and response schemas. `PATCH /roadmap-annotations/{roadmap_annotation}` Update roadmap annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | -------------------- | -------- | -------- | ------------------------- | | `roadmap_annotation` | path | Yes | The roadmap annotation ID | ### roadmap\_annotation ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "overlay", "marker" ], "title": "RoadmapAnnotationType" }, "annotation_type": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 255 }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] } }, "title": "UpdateRoadmapAnnotationRequest" } ``` ```json { "project_id": 101 } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/roadmap-annotations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `RoadmapAnnotationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "overlay", "marker" ], "title": "RoadmapAnnotationType" }, "annotation_type": { "type": "string" }, "label": { "type": "string" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "type", "annotation_type", "label", "start_date", "end_date", "notes", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "RoadmapAnnotationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z", "end_date": null, "notes": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-screen-annotations-screen-annotation # Update screen annotation PATCH /screen-annotations/{screen\_annotation}. Parameters, permissions, request and response schemas. `PATCH /screen-annotations/{screen_annotation}` Update screen annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------------- | -------- | -------- | ------------------------ | | `screen_annotation` | path | Yes | The screen annotation ID | ### screen\_annotation ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "note": { "type": "string", "maxLength": 65535 }, "insight_label_id": { "type": "integer" }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 }, "width": { "type": [ "integer", "null" ], "minimum": 1 }, "height": { "type": [ "integer", "null" ], "minimum": 1 }, "shape": { "type": "string", "enum": [ "point", "rect" ] }, "metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] } }, "title": "UpdateScreenAnnotationRequest" } ``` ```json { "project_id": 101 } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/screen-annotations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ScreenAnnotationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "screen_id": { "type": "integer" }, "insight_label_id": { "type": [ "integer", "null" ] }, "note": { "type": [ "string", "null" ] }, "x": { "type": [ "integer", "null" ] }, "y": { "type": [ "integer", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "shape": { "type": "string" }, "metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "screen_id", "insight_label_id", "note", "x", "y", "width", "height", "shape", "metadata", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "ScreenAnnotationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "screen_id": 101, "insight_label_id": null, "note": null, "x": null, "y": null, "width": null, "height": null, "shape": "example", "metadata": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-screens-screen # Update screen PATCH /screens/{screen}. Parameters, permissions, request and response schemas. `PATCH /screens/{screen}` Update screen. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | -------- | -------- | -------- | ------------- | | `screen` | path | Yes | The screen ID | ### screen ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "audience_id": { "type": [ "integer", "null" ] }, "page_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 } }, "title": "UpdateScreenRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/screens/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ScreenResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "audience_id": { "type": [ "integer", "null" ] }, "page_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "audience_id", "page_id", "name", "description", "image", "width", "height", "created_at", "updated_at", "deleted_at" ], "title": "ScreenResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "audience_id": null, "page_id": null, "name": null, "description": null, "image": null, "width": null, "height": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-tags-tag # Update tag PATCH /tags/{tag}. Parameters, permissions, request and response schemas. `PATCH /tags/{tag}` Update tag. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ----- | -------- | -------- | ----------- | | `tag` | path | Yes | The tag ID | ### tag ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] } }, "title": "UpdateTagRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/tags/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `TagResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "generic", "page", "device", "insight-detail-type", "audience" ], "title": "TagType" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "type", "description", "created_at", "updated_at" ], "title": "TagResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "type": "generic", "description": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/patch-variations-variation # Update variation PATCH /variations/{variation}. Parameters, permissions, request and response schemas. `PATCH /variations/{variation}` Update variation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ----------- | -------- | -------- | ---------------- | | `variation` | path | Yes | The variation ID | ### variation ```json { "type": "integer", "minimum": 1 } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "traffic_percentage": { "type": "number", "minimum": 0, "maximum": 1 }, "traffic_locked": { "type": "boolean" }, "is_baseline": { "type": "boolean" } }, "required": [ "project_id", "experiment_id" ], "title": "UpdateVariationRequest" } ``` ```json { "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate" } ``` ## Example request ```bash curl --request PATCH 'https://api.example.test/api/variations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"experiment_id":101,"name":"Checkout delivery estimate"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `VariationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "name": { "type": "string" }, "traffic_percentage": { "type": "number" }, "traffic_locked": { "type": "boolean" }, "is_baseline": { "type": "boolean" }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "experiment_id", "name", "traffic_percentage", "traffic_locked", "is_baseline", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at" ], "title": "VariationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate", "traffic_percentage": 1, "traffic_locked": true, "is_baseline": true, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-attachments # Create attachment POST /attachments. Parameters, permissions, request and response schemas. `POST /attachments` Create attachment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### multipart/form-data ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "type": { "type": "string", "enum": [ "image", "document", "link" ], "title": "AttachmentType" }, "file": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 10240 kilobytes." }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "attachable_type": { "type": "string", "enum": [ "experiment", "idea", "insight", "variation" ] }, "attachable_id": { "type": "integer" } }, "required": [ "project_id", "type", "attachable_type", "attachable_id" ], "title": "StoreAttachmentRequest", "description": "For image/document attachments, file is required (up to 10 MB; JPEG, PNG, GIF, PDF, DOC/DOCX, XLS/XLSX). For link attachments, url is required. The linked record must exist in this Team.", "allOf": [ { "if": { "properties": { "type": { "enum": [ "image", "document" ] } }, "required": [ "type" ] }, "then": { "required": [ "file" ] } }, { "if": { "properties": { "type": { "const": "link" } }, "required": [ "type" ] }, "then": { "required": [ "url" ] } } ], "example": { "project_id": 101, "type": "link", "url": "https://example.com/research", "attachable_type": "idea", "attachable_id": 101 } } ``` ```json { "project_id": 101, "type": "link", "url": "https://example.com/research", "attachable_type": "idea", "attachable_id": 101 } ``` ## Example request For file fields, replace the synthetic local filename with an existing file of the documented type and size. Let curl set the multipart boundary. ```bash curl --request POST 'https://api.example.test/api/attachments' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --form-string 'project_id=101' \ --form-string 'type=link' \ --form-string 'attachable_type=idea' \ --form-string 'attachable_id=101' \ --form-string 'url=https://example.com/research' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `AttachmentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "file_type": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "image", "document", "link" ], "title": "AttachmentType" }, "url": { "type": [ "string", "null" ] }, "attachable_type": { "type": "string" }, "attachable_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "file_type", "file_size", "type", "url", "attachable_type", "attachable_id", "created_at", "updated_at" ], "title": "AttachmentResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-audiences # Create audience POST /audiences. Parameters, permissions, request and response schemas. `POST /audiences` Create audience. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 } }, "required": [ "project_id", "name" ], "title": "StoreAudienceRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/audiences' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 201 `AudienceResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-comments # Create comment POST /comments. Parameters, permissions, request and response schemas. `POST /comments` Create comment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "commentable_type": { "type": "string", "enum": [ "insight", "idea", "experiment" ] }, "commentable_id": { "type": "integer", "minimum": 1 }, "body": { "type": "string", "maxLength": 5000 }, "parent_id": { "type": [ "integer", "null" ] } }, "required": [ "commentable_type", "commentable_id", "body" ], "title": "StoreCommentRequest" } ``` ```json { "commentable_type": "insight", "commentable_id": 101, "body": "example" } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/comments' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"commentable_type":"insight","commentable_id":101,"body":"example"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 201 `CommentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "body": { "type": "string" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "seat_type": { "type": [ "string", "null" ] }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "email", "role", "seat_type", "email_verified_at", "created_at", "updated_at", "last_login_at" ], "title": "UserResource" }, { "type": "null" } ] }, "user_id": { "type": [ "integer", "null" ] }, "parent_id": { "type": [ "integer", "null" ] }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/CommentResource" } }, "is_approved": { "type": "boolean" }, "commentable_type": { "type": "string" }, "commentable_id": { "type": "integer" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "body", "user_id", "parent_id", "is_approved", "commentable_type", "commentable_id", "can_edit", "can_delete", "created_at", "updated_at" ], "title": "CommentResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "body": "example", "user_id": null, "parent_id": null, "is_approved": true, "commentable_type": "example", "commentable_id": 101, "can_edit": true, "can_delete": true, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-experiment-states # Create experiment state POST /experiment-states. Parameters, permissions, request and response schemas. `POST /experiment-states` Create experiment state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "category": { "type": "string", "enum": [ "draft", "live", "paused", "finished", "archived" ], "title": "ExperimentStateCategory" } }, "required": [ "project_id", "name", "category" ], "title": "StoreExperimentStateRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null, "category": "draft" } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/experiment-states' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null,"category":"draft"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ExperimentStateResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "category": { "anyOf": [ { "type": "string", "enum": [ "draft", "live", "paused", "finished", "archived" ], "title": "ExperimentStateCategory" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "category", "order", "created_at", "updated_at" ], "title": "ExperimentStateResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "description": null, "category": null, "order": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-experiments-bulk # Apply a bulk action to experiments POST /experiments/bulk. Parameters, permissions, request and response schemas. `POST /experiments/bulk` Apply a bulk action to experiments. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "action": { "type": "string", "enum": [ "archive", "delete", "duplicate" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "action", "ids" ], "title": "BulkExperimentActionRequest" } ``` ```json { "action": "archive", "ids": [ 1 ] } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/experiments/bulk' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"action":"archive","ids":[1]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `ExperimentResource` Content type: `application/json`. ```json { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "archive" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } } }, "required": [ "data" ] } ] } ``` ```json { "action": "delete", "count": 1 } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-experiments-experiment-approvals # Record experiment approvals POST /experiments/{experiment}/approvals. Parameters, permissions, request and response schemas. `POST /experiments/{experiment}/approvals` Record experiment approvals. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `experiment` | path | Yes | The experiment ID | ### experiment ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "notes": { "type": [ "string", "null" ], "maxLength": 5000 } } } ``` ```json {} ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/experiments/1/approvals' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 201 `ExperimentApprovalResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "experiment_id": 101, "user_id": 101, "status": "example", "notes": null, "approved_at": "example", "created_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-experiments-experiment-distribute-traffic # Distribute traffic for experiment POST /experiments/{experiment}/distribute-traffic. Parameters, permissions, request and response schemas. `POST /experiments/{experiment}/distribute-traffic` Distribute traffic for experiment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. No request body. Splits the remaining traffic equally among unlocked variations while preserving locked shares. A Live experiment returns 422. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `experiment` | path | Yes | The experiment ID | ### experiment ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/experiments/1/distribute-traffic' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ExperimentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-experiments # Create experiment POST /experiments. Parameters, permissions, request and response schemas. `POST /experiments` Create experiment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, "state_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "project_id": { "type": "integer" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "idea_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "primary_metric_id": { "type": [ "integer", "null" ] }, "secondary_metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "uniqueItems": true }, "guardrail_metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "uniqueItems": true }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "type", "name" ], "title": "StoreExperimentRequest" } ``` ```json { "type": "ab_test", "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/experiments' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"type":"ab_test","name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ExperimentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-forms-bulk # Apply a bulk action to forms POST /forms/bulk. Parameters, permissions, request and response schemas. `POST /forms/bulk` Apply a bulk action to forms. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "action": { "type": "string", "enum": [ "delete", "publish", "change-status" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "FormStatus" } }, "required": [ "action", "ids" ], "title": "BulkFormActionRequest" } ``` ```json { "action": "delete", "ids": [ 1 ] } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/forms/bulk' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"action":"delete","ids":[1]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "description": "The bulk action from the request." }, "status": { "type": "string" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "status", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] } ] } ``` ```json { "action": "example", "status": "example", "count": 1 } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-forms-duplicate # Duplicate form POST /forms/duplicate. Parameters, permissions, request and response schemas. `POST /forms/duplicate` Duplicate form. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "ids" ], "title": "DuplicateFormsRequest" } ``` ```json { "ids": [ 1 ] } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/forms/duplicate' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"ids":[1]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `FormResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "widget", "inline", "link" ], "title": "FormType" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "FormStatus" }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "title", "description", "order", "created_at", "updated_at" ], "title": "FormStepResource" } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "responses_count": { "type": "integer" }, "submitted_responses_count": { "type": "integer", "minimum": 0 }, "partial_responses_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "public_id", "project_id", "name", "description", "type", "status", "settings", "created_at", "updated_at" ], "title": "FormResource" } } }, "required": [ "data" ] } ``` ```json { "data": [ { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "created_at": null, "updated_at": null } ] } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-forms # Create form POST /forms. Parameters, permissions, request and response schemas. `POST /forms` Create form. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "widget", "inline", "link" ], "title": "FormType" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "FormStatus" }, "project_id": { "type": "integer" }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string", "maxLength": 500 }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" } }, "required": [ "type", "title" ] } } } } } }, "required": [ "name", "project_id" ], "title": "StoreFormRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/forms' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 201 `FormResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "widget", "inline", "link" ], "title": "FormType" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "FormStatus" }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "title", "description", "order", "created_at", "updated_at" ], "title": "FormStepResource" } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "responses_count": { "type": "integer" }, "submitted_responses_count": { "type": "integer", "minimum": 0 }, "partial_responses_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "public_id", "project_id", "name", "description", "type", "status", "settings", "created_at", "updated_at" ], "title": "FormResource" }, { "type": "object", "required": [ "steps" ] } ] } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "steps": [ { "id": 101, "form_id": 101, "title": null, "description": null, "order": 1, "created_at": null, "updated_at": null } ], "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-idea-states # Create idea state POST /idea-states. Parameters, permissions, request and response schemas. `POST /idea-states` Create idea state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "color": { "type": "string", "maxLength": 255 } }, "required": [ "project_id", "name", "color" ], "title": "StoreIdeaStateRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null, "color": "#3b82f6" } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/idea-states' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null,"color":"#3b82f6"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `IdeaStateResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "description": null, "color": null, "order": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-ideas-bulk # Apply a bulk action to ideas POST /ideas/bulk. Parameters, permissions, request and response schemas. `POST /ideas/bulk` Apply a bulk action to ideas. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "action": { "type": "string", "enum": [ "archive", "delete", "duplicate" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "action", "ids" ], "title": "BulkIdeaActionRequest" } ``` ```json { "action": "archive", "ids": [ 1 ] } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/ideas/bulk' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"action":"archive","ids":[1]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `IdeaResource` Content type: `application/json`. ```json { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "archive" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "audit", "insight", "experiment", "form", "api" ], "title": "IdeaSourceType" }, { "type": "null" } ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_name": { "type": [ "string", "null" ] }, "priority_values": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_score": { "type": [ "number", "null" ] }, "priority_details": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_calculated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" } }, "experiments_count": { "type": "integer" }, "insights_count": { "type": "integer" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "project_id", "state_id", "name", "description", "hypothesis", "user_id", "source", "source_id", "source_item_key", "source_name", "priority_values", "priority_score", "priority_details", "priority_calculated_at", "created_at", "updated_at" ], "title": "IdeaResource" } } }, "required": [ "data" ] } ] } ``` ```json { "action": "delete", "count": 1 } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-ideas # Create idea POST /ideas. Parameters, permissions, request and response schemas. `POST /ideas` Create idea. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "source": { "type": "string", "maxLength": 255 }, "source_name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "project_id": { "type": "integer" }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "experiment_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "metric_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "priority_values": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_score": { "type": [ "number", "null" ] }, "priority_details": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_calculated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "name", "project_id" ], "title": "StoreIdeaRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/ideas' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `IdeaResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "audit", "insight", "experiment", "form", "api" ], "title": "IdeaSourceType" }, { "type": "null" } ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_name": { "type": [ "string", "null" ] }, "priority_values": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_score": { "type": [ "number", "null" ] }, "priority_details": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_calculated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" } }, "experiments_count": { "type": "integer" }, "insights_count": { "type": "integer" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "project_id", "state_id", "name", "description", "hypothesis", "user_id", "source", "source_id", "source_item_key", "source_name", "priority_values", "priority_score", "priority_details", "priority_calculated_at", "created_at", "updated_at" ], "title": "IdeaResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "project_id": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_name": null, "priority_values": null, "priority_score": null, "priority_details": null, "priority_calculated_at": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-insight-labels # Create insight label POST /insight-labels. Parameters, permissions, request and response schemas. `POST /insight-labels` Create insight label. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "color": { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "InsightLabelColor" } }, "required": [ "project_id", "name", "color" ], "title": "StoreInsightLabelRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "color": "gray" } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/insight-labels' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","color":"gray"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `InsightLabelResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "InsightLabelColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "color", "order", "created_at", "updated_at", "deleted_at" ], "title": "InsightLabelResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "color": null, "order": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-insights-bulk # Apply a bulk action to insights POST /insights/bulk. Parameters, permissions, request and response schemas. `POST /insights/bulk` Apply a bulk action to insights. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "action": { "type": "string", "enum": [ "archive", "delete", "duplicate" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "action", "ids" ], "title": "BulkInsightActionRequest" } ``` ```json { "action": "archive", "ids": [ 1 ] } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/insights/bulk' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"action":"archive","ids":[1]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `InsightResource` Content type: `application/json`. ```json { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "archive" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } } }, "required": [ "data" ] } ] } ``` ```json { "action": "delete", "count": 1 } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-insights # Create insight POST /insights. Parameters, permissions, request and response schemas. `POST /insights` Create insight. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "source": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "project_id": { "type": "integer" }, "user_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "experiment_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "idea_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "observation_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "learning_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "screen_annotations": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "required": [ "name", "project_id" ], "title": "StoreInsightRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/insights' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `InsightResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "research_collection_id": null, "insight_label_id": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_label": null, "name": null, "description": null, "created_at": null, "updated_at": null, "deleted_at": null, "has_ideas": true } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-learnings-bulk # Apply a bulk action to learnings POST /learnings/bulk. Parameters, permissions, request and response schemas. `POST /learnings/bulk` Apply a bulk action to learnings. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "action": { "type": "string", "enum": [ "archive", "delete", "duplicate" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "action", "ids" ], "title": "BulkLearningActionRequest" } ``` ```json { "action": "archive", "ids": [ 1 ] } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/learnings/bulk' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"action":"archive","ids":[1]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `LearningResource` Content type: `application/json`. ```json { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "archive" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "confidence": { "type": [ "string", "null" ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "confidence", "learned_at", "created_at", "updated_at", "deleted_at" ], "title": "LearningResource" } } }, "required": [ "data" ] } ] } ``` ```json { "action": "delete", "count": 1 } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-learnings # Create learning POST /learnings. Parameters, permissions, request and response schemas. `POST /learnings` Create learning. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "required": [ "project_id", "name" ], "title": "StoreLearningRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/learnings' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `LearningResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "confidence": { "type": [ "string", "null" ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "confidence", "learned_at", "created_at", "updated_at", "deleted_at" ], "title": "LearningResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "confidence": null, "learned_at": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-metrics # Create metric POST /metrics. Parameters, permissions, request and response schemas. `POST /metrics` Create metric. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "winning_direction": { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, "type": { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" } }, "required": [ "project_id", "name", "winning_direction", "type" ], "title": "StoreMetricRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null, "winning_direction": "increasing", "type": "average-per-user" } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/metrics' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null,"winning_direction":"increasing","type":"average-per-user"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 201 `MetricResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "description": null, "type": null, "winning_direction": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-numbering-schemes-numberingscheme-backfill # Backfill identifiers using numbering scheme POST /numbering-schemes/{numberingScheme}/backfill. Parameters, permissions, request and response schemas. `POST /numbering-schemes/{numberingScheme}/backfill` Backfill identifiers using numbering scheme. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ----------------- | -------- | -------- | ----------------------- | | `numberingScheme` | path | Yes | The numbering scheme ID | ### numberingScheme ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/numbering-schemes/1/backfill' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "backfilled": { "type": "integer" }, "scheme": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string" }, "template": { "type": "string" }, "initial_number": { "type": "integer" }, "is_active": { "type": "boolean" }, "claims_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "entity_type": { "type": "string" }, "assignment_scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "entity_type", "assignment_scope_key", "project_id" ] } }, "sequence_states": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] }, "project_code": { "type": [ "string", "null" ] }, "next_number": { "type": "integer" } }, "required": [ "id", "scope_key", "project_id", "project_code", "next_number" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "scope", "template", "initial_number", "is_active", "claims_count", "assignments", "sequence_states", "created_at", "updated_at" ] } }, "required": [ "backfilled", "scheme" ] } }, "required": [ "data" ] } ``` ```json { "data": { "backfilled": 1, "scheme": { "id": 101, "name": "Checkout delivery estimate", "scope": "example", "template": "example", "initial_number": 1, "is_active": true, "claims_count": "example", "assignments": [ { "id": 101, "entity_type": "example", "assignment_scope_key": "example", "project_id": null } ], "sequence_states": [ { "id": 101, "scope_key": "example", "project_id": null, "project_code": null, "next_number": 1 } ], "created_at": null, "updated_at": null } } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-numbering-schemes-preview # Preview numbering scheme POST /numbering-schemes/preview. Parameters, permissions, request and response schemas. `POST /numbering-schemes/preview` Preview numbering scheme. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "template": { "type": "string", "maxLength": 120 }, "entity_type": { "type": "string", "enum": [ "experiments", "ideas", "insights" ] }, "project_id": { "type": [ "integer", "null" ] }, "next_number": { "type": "integer", "minimum": 1 }, "project_code": { "type": [ "string", "null" ], "maxLength": 24 } }, "required": [ "template", "entity_type" ] } ``` ```json { "template": "example", "entity_type": "experiments", "project_id": null } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/numbering-schemes/preview' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"template":"example","entity_type":"experiments","project_id":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" }, { "type": "string" } ], "minItems": 3, "maxItems": 3 } }, "required": [ "data" ] } ``` ```json { "data": [ "example", "example", "example" ] } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-numbering-schemes # Create numbering scheme POST /numbering-schemes. Parameters, permissions, request and response schemas. `POST /numbering-schemes` Create numbering scheme. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "scope": { "type": "string", "enum": [ "team", "project" ] }, "template": { "type": "string", "maxLength": 120, "description": "Identifier template, for example EXP-{number:000}. Project-scoped templates may include {project_code}." }, "initial_number": { "type": "integer", "minimum": 1 }, "is_active": { "type": "boolean" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "experiments", "ideas", "insights" ] }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "entity_type" ] } } }, "example": { "name": "Experiment IDs", "scope": "team", "template": "EXP-{number:000}", "initial_number": 1, "assignments": [ { "entity_type": "experiments" } ] }, "required": [ "name", "scope", "template" ] } ``` ```json { "name": "Experiment IDs", "scope": "team", "template": "EXP-{number:000}", "initial_number": 1, "assignments": [ { "entity_type": "experiments" } ] } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/numbering-schemes' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Experiment IDs","scope":"team","template":"EXP-{number:000}","initial_number":1,"assignments":[{"entity_type":"experiments"}]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 201 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string" }, "template": { "type": "string" }, "initial_number": { "type": "integer" }, "is_active": { "type": "boolean" }, "claims_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "entity_type": { "type": "string" }, "assignment_scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "entity_type", "assignment_scope_key", "project_id" ] } }, "sequence_states": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] }, "project_code": { "type": [ "string", "null" ] }, "next_number": { "type": "integer" } }, "required": [ "id", "scope_key", "project_id", "project_code", "next_number" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "scope", "template", "initial_number", "is_active", "claims_count", "assignments", "sequence_states", "created_at", "updated_at" ] } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "name": "Checkout delivery estimate", "scope": "example", "template": "example", "initial_number": 1, "is_active": true, "claims_count": "example", "assignments": [ { "id": 101, "entity_type": "example", "assignment_scope_key": "example", "project_id": null } ], "sequence_states": [ { "id": 101, "scope_key": "example", "project_id": null, "project_code": null, "next_number": 1 } ], "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-observations-bulk # Apply a bulk action to observations POST /observations/bulk. Parameters, permissions, request and response schemas. `POST /observations/bulk` Apply a bulk action to observations. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "action": { "type": "string", "enum": [ "accept", "dismiss", "restore-dismissal", "archive", "delete", "duplicate" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "action", "ids" ], "title": "BulkObservationActionRequest" } ``` ```json { "action": "accept", "ids": [ 1 ] } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/observations/bulk' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"action":"accept","ids":[1]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Array of `ObservationResource` Content type: `application/json`. ```json { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "archive" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "description": "The bulk action from the request." }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "evidence_kind": { "type": [ "string", "null" ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked": { "type": "boolean" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by": { "type": [ "integer", "null" ] }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_status": { "type": "string" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "source_type", "source_id", "source_item_key", "source_label", "evidence_kind", "evidence_payload", "confidence", "observed_at", "locked", "accepted_at", "accepted_by", "dismissed_at", "dismissed_by", "created_at", "updated_at", "deleted_at", "review_status" ], "title": "ObservationResource" } } }, "required": [ "data" ] } ] } ``` ```json { "action": "delete", "count": 1 } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-observations-observation-accept # Accept observation POST /observations/{observation}/accept. Parameters, permissions, request and response schemas. `POST /observations/{observation}/accept` Accept observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------- | -------- | -------- | ------------------ | | `observation` | path | Yes | The observation ID | ### observation ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/observations/1/accept' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ObservationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "evidence_kind": { "type": [ "string", "null" ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked": { "type": "boolean" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by": { "type": [ "integer", "null" ] }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_status": { "type": "string" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "source_type", "source_id", "source_item_key", "source_label", "evidence_kind", "evidence_payload", "confidence", "observed_at", "locked", "accepted_at", "accepted_by", "dismissed_at", "dismissed_by", "created_at", "updated_at", "deleted_at", "review_status" ], "title": "ObservationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-observations-observation-dismiss # Dismiss observation POST /observations/{observation}/dismiss. Parameters, permissions, request and response schemas. `POST /observations/{observation}/dismiss` Dismiss observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------- | -------- | -------- | ------------------ | | `observation` | path | Yes | The observation ID | ### observation ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/observations/1/dismiss' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ObservationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "evidence_kind": { "type": [ "string", "null" ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked": { "type": "boolean" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by": { "type": [ "integer", "null" ] }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_status": { "type": "string" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "source_type", "source_id", "source_item_key", "source_label", "evidence_kind", "evidence_payload", "confidence", "observed_at", "locked", "accepted_at", "accepted_by", "dismissed_at", "dismissed_by", "created_at", "updated_at", "deleted_at", "review_status" ], "title": "ObservationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-observations-observation-restore-dismissal # Restore a dismissed observation POST /observations/{observation}/restore-dismissal. Parameters, permissions, request and response schemas. `POST /observations/{observation}/restore-dismissal` Restore a dismissed observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------- | -------- | -------- | ------------------ | | `observation` | path | Yes | The observation ID | ### observation ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/observations/1/restore-dismissal' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ObservationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "evidence_kind": { "type": [ "string", "null" ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked": { "type": "boolean" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by": { "type": [ "integer", "null" ] }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_status": { "type": "string" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "source_type", "source_id", "source_item_key", "source_label", "evidence_kind", "evidence_payload", "confidence", "observed_at", "locked", "accepted_at", "accepted_by", "dismissed_at", "dismissed_by", "created_at", "updated_at", "deleted_at", "review_status" ], "title": "ObservationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-observations-observation-restore # Restore an archived observation POST /observations/{observation}/restore. Parameters, permissions, request and response schemas. `POST /observations/{observation}/restore` Restore an archived observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------- | -------- | -------- | ------------ | | `observation` | path | Yes | Observation. | ### observation ```json { "type": "integer", "minimum": 1 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/observations/1/restore' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ObservationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "evidence_kind": { "type": [ "string", "null" ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked": { "type": "boolean" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by": { "type": [ "integer", "null" ] }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_status": { "type": "string" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "source_type", "source_id", "source_item_key", "source_label", "evidence_kind", "evidence_payload", "confidence", "observed_at", "locked", "accepted_at", "accepted_by", "dismissed_at", "dismissed_by", "created_at", "updated_at", "deleted_at", "review_status" ], "title": "ObservationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-observations # Create observation POST /observations. Parameters, permissions, request and response schemas. `POST /observations` Create observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "source_type": { "type": [ "string", "null" ], "enum": [ "manual", "audit", "experiment", "survey", "screen", "import", "external_research", null ] }, "source_id": { "type": [ "integer", "null" ], "minimum": 1 }, "source_item_key": { "type": [ "string", "null" ], "maxLength": 255 }, "source_label": { "type": [ "string", "null" ], "maxLength": 255 }, "evidence_kind": { "type": [ "string", "null" ], "enum": [ "screenshot_region", "quote", "metric_result", "page_text", "manual_note", "audit_observation", null ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "screen_annotation_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "required": [ "project_id", "name" ], "title": "StoreObservationRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/observations' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ObservationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "evidence_kind": { "type": [ "string", "null" ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked": { "type": "boolean" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by": { "type": [ "integer", "null" ] }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_status": { "type": "string" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "source_type", "source_id", "source_item_key", "source_label", "evidence_kind", "evidence_payload", "confidence", "observed_at", "locked", "accepted_at", "accepted_by", "dismissed_at", "dismissed_by", "created_at", "updated_at", "deleted_at", "review_status" ], "title": "ObservationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-pages # Create page POST /pages. Parameters, permissions, request and response schemas. `POST /pages` Create page. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] } }, "required": [ "project_id", "name" ], "title": "StorePageRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/pages' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 201 `PageResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-prio-models-id-recalculate # Recalculate priorities with prio model POST /prio-models/{id}/recalculate. Parameters, permissions, request and response schemas. `POST /prio-models/{id}/recalculate` Recalculate priorities with prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ---- | -------- | -------- | ----------- | | `id` | path | Yes | Id. | ### id ```json { "type": "integer", "minimum": 1 } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "id": { "type": "integer" } }, "required": [ "project_id", "id" ], "title": "RecalculatePrioModelRequest" } ``` ```json { "project_id": 101, "id": 101 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/prio-models/101/recalculate' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "const": "Priorities recalculated successfully" } }, "required": [ "message" ] } ``` ```json { "message": "Priorities recalculated successfully" } ``` ### 400 The request failed. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "const": "No prioritization configuration found for this project" } }, "required": [ "message" ] } ``` ```json { "message": "No prioritization configuration found for this project" } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-prio-models-validate-formula # Validate the formula for prio model POST /prio-models/validate-formula. Parameters, permissions, request and response schemas. `POST /prio-models/validate-formula` Validate the formula for prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "number", "boolean" ] }, "weight": { "type": "number" } }, "required": [ "key", "type", "weight" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ], "title": "ValidatePrioModelFormulaRequest", "example": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Impact", "key": "impact", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Confidence", "key": "confidence", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Effort", "key": "effort", "type": "number", "min": 1, "max": 10, "weight": 1 } ] } } ``` ```json { "formula": "impact * confidence / effort", "inputs": [ { "name": "Impact", "key": "impact", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Confidence", "key": "confidence", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Effort", "key": "effort", "type": "number", "min": 1, "max": 10, "weight": 1 } ] } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/prio-models/validate-formula' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"formula":"impact * confidence / effort","inputs":[{"name":"Impact","key":"impact","type":"number","min":1,"max":10,"weight":1},{"name":"Confidence","key":"confidence","type":"number","min":1,"max":10,"weight":1},{"name":"Effort","key":"effort","type":"number","min":1,"max":10,"weight":1}]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "valid": { "type": "boolean" }, "message": { "type": "string", "const": "Formula is valid" }, "sample_result": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "sample_values": { "type": "object", "additionalProperties": { "type": [ "number", "boolean" ] } } }, "required": [ "valid", "message", "sample_result", "sample_values" ], "example": { "valid": true, "message": "Formula is valid", "sample_result": 5, "sample_values": { "impact": 5, "confidence": 5, "effort": 5 } } } ``` ```json { "valid": true, "message": "Formula is valid", "sample_result": 5, "sample_values": { "impact": 5, "confidence": 5, "effort": 5 } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation failed or the expression cannot be evaluated. Content type: `application/json`. ```json { "anyOf": [ { "type": "object", "properties": { "valid": { "type": "boolean", "const": false }, "message": { "type": "string" }, "sample_values": { "type": "object", "additionalProperties": { "type": [ "number", "boolean" ] } } }, "required": [ "valid", "message", "sample_values" ] }, { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ] } ``` ```json { "valid": false, "message": "The request could not be completed.", "sample_values": {} } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-prio-models # Create prio model POST /prio-models. Parameters, permissions, request and response schemas. `POST /prio-models` Create prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "default_config": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "key": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "select" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "default": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] } }, "required": [ "name", "key", "type" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ] } }, "required": [ "name", "default_config" ], "title": "StorePrioModelRequest", "example": { "name": "ICE", "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Impact", "key": "impact", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Confidence", "key": "confidence", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Effort", "key": "effort", "type": "number", "min": 1, "max": 10, "weight": 1 } ] } } } ``` ```json { "name": "ICE", "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Impact", "key": "impact", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Confidence", "key": "confidence", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Effort", "key": "effort", "type": "number", "min": 1, "max": 10, "weight": 1 } ] } } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/prio-models' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"ICE","default_config":{"formula":"impact * confidence / effort","inputs":[{"name":"Impact","key":"impact","type":"number","min":1,"max":10,"weight":1},{"name":"Confidence","key":"confidence","type":"number","min":1,"max":10,"weight":1},{"name":"Effort","key":"effort","type":"number","min":1,"max":10,"weight":1}]}}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 201 `PrioModelResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "default_config": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "key": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "select" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "default": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] } }, "required": [ "name", "key", "type" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "description", "default_config", "created_at", "updated_at" ], "title": "PrioModelResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] }, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-projects-project # Update project POST /projects/{project}. Parameters, permissions, request and response schemas. `POST /projects/{project}` Update project. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | -------------- | | `project` | path | Yes | The project ID | ### project ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### multipart/form-data ```json { "type": "object", "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "active", "archived" ], "title": "ProjectState" }, { "type": "null" } ] }, "name": { "type": "string", "maxLength": 255, "description": "Must be unique among projects in this Team, excluding the project being updated." }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 1024 kilobytes." }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "ProjectColor" }, { "type": "null" } ] }, "prio_model_id": { "type": [ "integer", "null" ] } }, "title": "UpdateProjectRequest" } ``` ```json { "name": "Checkout delivery estimate" } ``` ## Example request For file fields, replace the synthetic local filename with an existing file of the documented type and size. Let curl set the multipart boundary. ```bash curl --request POST 'https://api.example.test/api/projects/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --form-string 'name=Checkout delivery estimate' \ --form 'cover=@./screenshot.png' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ProjectResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "public_id": { "type": "string" }, "state": { "anyOf": [ { "type": "string", "enum": [ "active", "archived" ], "title": "ProjectState" }, { "type": "null" } ] }, "name": { "type": "string" }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "ProjectColor" }, { "type": "null" } ] }, "prio_model_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "public_id", "state", "name", "cover", "color", "prio_model_id", "created_at", "updated_at" ], "title": "ProjectResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-projects # Create project POST /projects. Parameters, permissions, request and response schemas. `POST /projects` Create project. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### multipart/form-data ```json { "type": "object", "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "active", "archived" ], "title": "ProjectState" }, { "type": "null" } ] }, "name": { "type": "string", "maxLength": 255 }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 25600 kilobytes." }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "ProjectColor" }, { "type": "null" } ] } }, "required": [ "name" ], "title": "StoreProjectRequest" } ``` ```json { "name": "Checkout delivery estimate" } ``` ## Example request For file fields, replace the synthetic local filename with an existing file of the documented type and size. Let curl set the multipart boundary. ```bash curl --request POST 'https://api.example.test/api/projects' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --form-string 'name=Checkout delivery estimate' \ --form 'cover=@./screenshot.png' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ProjectResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "public_id": { "type": "string" }, "state": { "anyOf": [ { "type": "string", "enum": [ "active", "archived" ], "title": "ProjectState" }, { "type": "null" } ] }, "name": { "type": "string" }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "ProjectColor" }, { "type": "null" } ] }, "prio_model_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "public_id", "state", "name", "cover", "color", "prio_model_id", "created_at", "updated_at" ], "title": "ProjectResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-research-collections-research-collection # Update research collection POST /research-collections/{research\_collection}. Parameters, permissions, request and response schemas. `POST /research-collections/{research_collection}` Update research collection. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------------------- | -------- | -------- | -------------------------- | | `research_collection` | path | Yes | The research collection ID | ### research\_collection ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### multipart/form-data ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 1024 kilobytes." } }, "title": "UpdateResearchCollectionRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request For file fields, replace the synthetic local filename with an existing file of the documented type and size. Let curl set the multipart boundary. ```bash curl --request POST 'https://api.example.test/api/research-collections/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --form-string 'project_id=101' \ --form-string 'name=Checkout delivery estimate' \ --form 'cover=@./screenshot.png' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ResearchCollectionResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "cover", "created_at", "updated_at" ], "title": "ResearchCollectionResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` ### 500 The request failed. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "Error uploading file" } }, "required": [ "error" ] } ``` ```json { "error": "Error uploading file" } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-research-collections # Create research collection POST /research-collections. Parameters, permissions, request and response schemas. `POST /research-collections` Create research collection. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### multipart/form-data ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 1024 kilobytes." } }, "required": [ "project_id", "name" ], "title": "StoreResearchCollectionRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request For file fields, replace the synthetic local filename with an existing file of the documented type and size. Let curl set the multipart boundary. ```bash curl --request POST 'https://api.example.test/api/research-collections' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --form-string 'project_id=101' \ --form-string 'name=Checkout delivery estimate' \ --form 'cover=@./screenshot.png' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ResearchCollectionResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "cover", "created_at", "updated_at" ], "title": "ResearchCollectionResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` ### 500 The request failed. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "Error uploading file" } }, "required": [ "error" ] } ``` ```json { "error": "Error uploading file" } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-roadmap-annotations # Create roadmap annotation POST /roadmap-annotations. Parameters, permissions, request and response schemas. `POST /roadmap-annotations` Create roadmap annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "overlay", "marker" ], "title": "RoadmapAnnotationType" }, "annotation_type": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 255 }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] } }, "required": [ "project_id", "type", "annotation_type", "label", "start_date" ], "title": "StoreRoadmapAnnotationRequest" } ``` ```json { "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z" } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/roadmap-annotations' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"type":"overlay","annotation_type":"example","label":"example","start_date":"2026-01-15T12:00:00Z"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `RoadmapAnnotationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "overlay", "marker" ], "title": "RoadmapAnnotationType" }, "annotation_type": { "type": "string" }, "label": { "type": "string" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "type", "annotation_type", "label", "start_date", "end_date", "notes", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "RoadmapAnnotationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z", "end_date": null, "notes": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-screen-annotations # Create screen annotation POST /screen-annotations. Parameters, permissions, request and response schemas. `POST /screen-annotations` Create screen annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "screen_id": { "type": "integer" }, "note": { "type": [ "string", "null" ], "maxLength": 65535 }, "insight_label_id": { "type": "integer" }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 }, "width": { "type": [ "integer", "null" ], "minimum": 1 }, "height": { "type": [ "integer", "null" ], "minimum": 1 }, "shape": { "type": "string", "enum": [ "point", "rect" ] }, "metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] } }, "required": [ "project_id", "screen_id", "x", "y" ], "title": "StoreScreenAnnotationsRequest" } ``` ```json { "project_id": 101, "screen_id": 101, "x": 1, "y": 1 } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/screen-annotations' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"screen_id":101,"x":1,"y":1}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ScreenAnnotationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "screen_id": { "type": "integer" }, "insight_label_id": { "type": [ "integer", "null" ] }, "note": { "type": [ "string", "null" ] }, "x": { "type": [ "integer", "null" ] }, "y": { "type": [ "integer", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "shape": { "type": "string" }, "metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "screen_id", "insight_label_id", "note", "x", "y", "width", "height", "shape", "metadata", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "ScreenAnnotationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "screen_id": 101, "insight_label_id": null, "note": null, "x": null, "y": null, "width": null, "height": null, "shape": "example", "metadata": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-screens # Create screen POST /screens. Parameters, permissions, request and response schemas. `POST /screens` Create screen. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### multipart/form-data ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "audience_id": { "type": [ "integer", "null" ] }, "page_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "image": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 25600 kilobytes." } }, "required": [ "project_id", "name", "image" ], "title": "StoreScreenRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null, "image": "screenshot.png" } ``` ## Example request For file fields, replace the synthetic local filename with an existing file of the documented type and size. Let curl set the multipart boundary. ```bash curl --request POST 'https://api.example.test/api/screens' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --form-string 'project_id=101' \ --form-string 'name=Checkout delivery estimate' \ --form 'image=@./screenshot.png' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ScreenResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "audience_id": { "type": [ "integer", "null" ] }, "page_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "audience_id", "page_id", "name", "description", "image", "width", "height", "created_at", "updated_at", "deleted_at" ], "title": "ScreenResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "audience_id": null, "page_id": null, "name": null, "description": null, "image": null, "width": null, "height": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` ### 500 The request failed. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "Error uploading file" } }, "required": [ "error" ] } ``` ```json { "error": "Error uploading file" } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-tags # Create tag POST /tags. Parameters, permissions, request and response schemas. `POST /tags` Create tag. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "generic", "page", "device", "insight-detail-type", "audience" ], "title": "TagType" }, "description": { "type": [ "string", "null" ] } }, "required": [ "project_id", "name", "type" ], "title": "StoreTagRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "type": "generic", "description": null } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/tags' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","type":"generic","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 201 `TagResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "generic", "page", "device", "insight-detail-type", "audience" ], "title": "TagType" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "type", "description", "created_at", "updated_at" ], "title": "TagResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "type": "generic", "description": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/post-variations # Create variation POST /variations. Parameters, permissions, request and response schemas. `POST /variations` Create variation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "traffic_percentage": { "type": "number", "minimum": 0, "maximum": 1 }, "traffic_locked": { "type": "boolean" }, "is_baseline": { "type": "boolean" } }, "required": [ "project_id", "experiment_id", "name" ], "title": "StoreVariationRequest" } ``` ```json { "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate" } ``` ## Example request ```bash curl --request POST 'https://api.example.test/api/variations' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"experiment_id":101,"name":"Checkout delivery estimate"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 201 `VariationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "name": { "type": "string" }, "traffic_percentage": { "type": "number" }, "traffic_locked": { "type": "boolean" }, "is_baseline": { "type": "boolean" }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "experiment_id", "name", "traffic_percentage", "traffic_locked", "is_baseline", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at" ], "title": "VariationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate", "traffic_percentage": 1, "traffic_locked": true, "is_baseline": true, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-attachments-attachment # Update attachment PUT /attachments/{attachment}. Parameters, permissions, request and response schemas. `PUT /attachments/{attachment}` Update attachment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `attachment` | path | Yes | The attachment ID | ### attachment ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 } }, "title": "UpdateAttachmentRequest" } ``` ```json { "name": "Checkout delivery estimate" } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/attachments/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `AttachmentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "file_type": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "image", "document", "link" ], "title": "AttachmentType" }, "url": { "type": [ "string", "null" ] }, "attachable_type": { "type": "string" }, "attachable_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "file_type", "file_size", "type", "url", "attachable_type", "attachable_id", "created_at", "updated_at" ], "title": "AttachmentResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-audiences-audience # Update audience PUT /audiences/{audience}. Parameters, permissions, request and response schemas. `PUT /audiences/{audience}` Update audience. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ---------- | -------- | -------- | --------------- | | `audience` | path | Yes | The audience ID | ### audience ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 } }, "title": "UpdateAudienceRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/audiences/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `AudienceResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-comments-comment # Update comment PUT /comments/{comment}. Parameters, permissions, request and response schemas. `PUT /comments/{comment}` Update comment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | -------------- | | `comment` | path | Yes | The comment ID | ### comment ```json { "type": "integer", "minimum": 1 } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "body": { "type": "string", "maxLength": 5000 } }, "required": [ "body" ], "title": "UpdateCommentRequest" } ``` ```json { "body": "example" } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/comments/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"body":"example"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `CommentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "body": { "type": "string" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "seat_type": { "type": [ "string", "null" ] }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "email", "role", "seat_type", "email_verified_at", "created_at", "updated_at", "last_login_at" ], "title": "UserResource" }, { "type": "null" } ] }, "user_id": { "type": [ "integer", "null" ] }, "parent_id": { "type": [ "integer", "null" ] }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/CommentResource" } }, "is_approved": { "type": "boolean" }, "commentable_type": { "type": "string" }, "commentable_id": { "type": "integer" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "body", "user_id", "parent_id", "is_approved", "commentable_type", "commentable_id", "can_edit", "can_delete", "created_at", "updated_at" ], "title": "CommentResource" }, { "type": "object", "required": [ "user" ] } ] } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "body": "example", "user": null, "user_id": null, "parent_id": null, "is_approved": true, "commentable_type": "example", "commentable_id": 101, "can_edit": true, "can_delete": true, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-experiment-states-experiment-state # Update experiment state PUT /experiment-states/{experiment\_state}. Parameters, permissions, request and response schemas. `PUT /experiment-states/{experiment_state}` Update experiment state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------------ | -------- | -------- | ----------------------- | | `experiment_state` | path | Yes | The experiment state ID | ### experiment\_state ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "category": { "type": "string", "enum": [ "draft", "live", "paused", "finished", "archived" ], "title": "ExperimentStateCategory" }, "order": { "type": "integer", "minimum": 0 } }, "title": "UpdateExperimentStateRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/experiment-states/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ExperimentStateResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "category": { "anyOf": [ { "type": "string", "enum": [ "draft", "live", "paused", "finished", "archived" ], "title": "ExperimentStateCategory" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "category", "order", "created_at", "updated_at" ], "title": "ExperimentStateResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "description": null, "category": null, "order": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-experiment-states-order # Reorder experiment states PUT /experiment-states/order. Parameters, permissions, request and response schemas. `PUT /experiment-states/order` Reorder experiment states. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "ids" ], "title": "OrderExperimentStateRequest" } ``` ```json { "ids": [ 1 ] } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/experiment-states/order' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"ids":[1]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-experiments-experiment # Update experiment PUT /experiments/{experiment}. Parameters, permissions, request and response schemas. `PUT /experiments/{experiment}` Update experiment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `experiment` | path | Yes | The experiment ID | ### experiment ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, "state_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "source": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": "integer" }, "project_id": { "type": "integer" }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "idea_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "primary_metric_id": { "type": "integer" }, "secondary_metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "uniqueItems": true }, "guardrail_metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "uniqueItems": true }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" } }, "title": "UpdateExperimentRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/experiments/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ExperimentResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-forms-form # Update form PUT /forms/{form}. Parameters, permissions, request and response schemas. `PUT /forms/{form}` Update form. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `form` | path | Yes | The form ID | ### form ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "widget", "inline", "link" ], "title": "FormType" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "FormStatus" }, "project_id": { "type": "integer" }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string", "maxLength": 500 }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" } }, "required": [ "type", "title" ] } } } } } }, "title": "UpdateFormRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/forms/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `FormResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "widget", "inline", "link" ], "title": "FormType" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "FormStatus" }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "title", "description", "order", "created_at", "updated_at" ], "title": "FormStepResource" } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" } }, "responses_count": { "type": "integer" }, "submitted_responses_count": { "type": "integer", "minimum": 0 }, "partial_responses_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "public_id", "project_id", "name", "description", "type", "status", "settings", "created_at", "updated_at" ], "title": "FormResource" }, { "type": "object", "required": [ "steps" ] } ] } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "steps": [ { "id": 101, "form_id": 101, "title": null, "description": null, "order": 1, "created_at": null, "updated_at": null } ], "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-idea-states-idea-state # Update idea state PUT /idea-states/{idea\_state}. Parameters, permissions, request and response schemas. `PUT /idea-states/{idea_state}` Update idea state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `idea_state` | path | Yes | The idea state ID | ### idea\_state ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "color": { "type": [ "string", "null" ], "maxLength": 255 }, "order": { "type": [ "integer", "null" ], "minimum": 0 } }, "title": "UpdateIdeaStateRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/idea-states/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `IdeaStateResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "description": null, "color": null, "order": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-idea-states-order # Reorder idea states PUT /idea-states/order. Parameters, permissions, request and response schemas. `PUT /idea-states/order` Reorder idea states. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "ids" ], "title": "OrderIdeaStateRequest" } ``` ```json { "ids": [ 1 ] } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/idea-states/order' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"ids":[1]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 204 No content ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-ideas-idea # Update idea PUT /ideas/{idea}. Parameters, permissions, request and response schemas. `PUT /ideas/{idea}` Update idea. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `idea` | path | Yes | The idea ID | ### idea ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "source": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "project_id": { "type": "integer" }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "experiment_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "priority_values": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] } }, "title": "UpdateIdeaRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/ideas/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `IdeaResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "audit", "insight", "experiment", "form", "api" ], "title": "IdeaSourceType" }, { "type": "null" } ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_name": { "type": [ "string", "null" ] }, "priority_values": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_score": { "type": [ "number", "null" ] }, "priority_details": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "priority_calculated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" } }, "experiments_count": { "type": "integer" }, "insights_count": { "type": "integer" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "project_id", "state_id", "name", "description", "hypothesis", "user_id", "source", "source_id", "source_item_key", "source_name", "priority_values", "priority_score", "priority_details", "priority_calculated_at", "created_at", "updated_at" ], "title": "IdeaResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "project_id": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_name": null, "priority_values": null, "priority_score": null, "priority_details": null, "priority_calculated_at": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-insight-labels-insight-label # Update insight label PUT /insight-labels/{insight\_label}. Parameters, permissions, request and response schemas. `PUT /insight-labels/{insight_label}` Update insight label. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------------- | -------- | -------- | -------------------- | | `insight_label` | path | Yes | The insight label ID | ### insight\_label ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "InsightLabelColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] } }, "title": "UpdateInsightLabelRequest" } ``` ```json { "project_id": 101, "name": null } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/insight-labels/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `InsightLabelResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "InsightLabelColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "color", "order", "created_at", "updated_at", "deleted_at" ], "title": "InsightLabelResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": null, "name": null, "color": null, "order": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-insights-insight # Update insight PUT /insights/{insight}. Parameters, permissions, request and response schemas. `PUT /insights/{insight}` Update insight. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | -------------- | | `insight` | path | Yes | The insight ID | ### insight ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "source": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "experiment_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "idea_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "observation_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "learning_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "screen_annotations": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } } }, "title": "UpdateInsightRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/insights/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `InsightResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "research_collection_id": null, "insight_label_id": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_label": null, "name": null, "description": null, "created_at": null, "updated_at": null, "deleted_at": null, "has_ideas": true } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-learnings-learning # Update learning PUT /learnings/{learning}. Parameters, permissions, request and response schemas. `PUT /learnings/{learning}` Update learning. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ---------- | -------- | -------- | --------------- | | `learning` | path | Yes | The learning ID | ### learning ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "title": "UpdateLearningRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/learnings/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `LearningResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "confidence": { "type": [ "string", "null" ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "confidence", "learned_at", "created_at", "updated_at", "deleted_at" ], "title": "LearningResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "confidence": null, "learned_at": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-metrics-metric # Update metric PUT /metrics/{metric}. Parameters, permissions, request and response schemas. `PUT /metrics/{metric}` Update metric. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | -------- | -------- | -------- | ------------- | | `metric` | path | Yes | The metric ID | ### metric ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "winning_direction": { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, "type": { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" } }, "title": "UpdateMetricRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/metrics/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `MetricResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "description": null, "type": null, "winning_direction": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-numbering-schemes-numberingscheme # Update numbering scheme PUT /numbering-schemes/{numberingScheme}. Parameters, permissions, request and response schemas. `PUT /numbering-schemes/{numberingScheme}` Update numbering scheme. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ----------------- | -------- | -------- | ----------------------- | | `numberingScheme` | path | Yes | The numbering scheme ID | ### numberingScheme ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "scope": { "type": "string", "enum": [ "team", "project" ] }, "template": { "type": "string", "maxLength": 120, "description": "Identifier template, for example EXP-{number:000}. Project-scoped templates may include {project_code}." }, "initial_number": { "type": "integer", "minimum": 1 }, "is_active": { "type": "boolean" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "experiments", "ideas", "insights" ] }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "entity_type" ] } } }, "example": { "name": "Experiment IDs", "scope": "team", "template": "EXP-{number:000}", "initial_number": 1, "assignments": [ { "entity_type": "experiments" } ] } } ``` ```json { "name": "Experiment IDs", "scope": "team", "template": "EXP-{number:000}", "initial_number": 1, "assignments": [ { "entity_type": "experiments" } ] } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/numbering-schemes/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Experiment IDs","scope":"team","template":"EXP-{number:000}","initial_number":1,"assignments":[{"entity_type":"experiments"}]}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 Successful response. Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string" }, "template": { "type": "string" }, "initial_number": { "type": "integer" }, "is_active": { "type": "boolean" }, "claims_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "entity_type": { "type": "string" }, "assignment_scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "entity_type", "assignment_scope_key", "project_id" ] } }, "sequence_states": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] }, "project_code": { "type": [ "string", "null" ] }, "next_number": { "type": "integer" } }, "required": [ "id", "scope_key", "project_id", "project_code", "next_number" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "scope", "template", "initial_number", "is_active", "claims_count", "assignments", "sequence_states", "created_at", "updated_at" ] } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "name": "Checkout delivery estimate", "scope": "example", "template": "example", "initial_number": 1, "is_active": true, "claims_count": "example", "assignments": [ { "id": 101, "entity_type": "example", "assignment_scope_key": "example", "project_id": null } ], "sequence_states": [ { "id": 101, "scope_key": "example", "project_id": null, "project_code": null, "next_number": 1 } ], "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Token ability, user permission, Team membership, plan, or billing mode does not allow this operation. Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] } ``` ```json { "message": "This action is unauthorized." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-observations-observation # Update observation PUT /observations/{observation}. Parameters, permissions, request and response schemas. `PUT /observations/{observation}` Update observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------- | -------- | -------- | ------------------ | | `observation` | path | Yes | The observation ID | ### observation ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "source_type": { "type": [ "string", "null" ], "enum": [ "manual", "audit", "experiment", "survey", "screen", "import", "external_research", null ] }, "source_id": { "type": [ "integer", "null" ], "minimum": 1 }, "source_item_key": { "type": [ "string", "null" ], "maxLength": 255 }, "source_label": { "type": [ "string", "null" ], "maxLength": 255 }, "evidence_kind": { "type": [ "string", "null" ], "enum": [ "screenshot_region", "quote", "metric_result", "page_text", "manual_note", "audit_observation", null ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "screen_annotation_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "title": "UpdateObservationRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/observations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ObservationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "evidence_kind": { "type": [ "string", "null" ] }, "evidence_payload": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "confidence": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked": { "type": "boolean" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by": { "type": [ "integer", "null" ] }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_status": { "type": "string" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "source_type", "source_id", "source_item_key", "source_label", "evidence_kind", "evidence_payload", "confidence", "observed_at", "locked", "accepted_at", "accepted_by", "dismissed_at", "dismissed_by", "created_at", "updated_at", "deleted_at", "review_status" ], "title": "ObservationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-pages-page # Update page PUT /pages/{page}. Parameters, permissions, request and response schemas. `PUT /pages/{page}` Update page. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------ | -------- | -------- | ----------- | | `page` | path | Yes | The page ID | ### page ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] } }, "title": "UpdatePageRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/pages/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `PageResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-prio-models-prio-model # Update prio model PUT /prio-models/{prio\_model}. Parameters, permissions, request and response schemas. `PUT /prio-models/{prio_model}` Update prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------ | -------- | -------- | ----------------- | | `prio_model` | path | Yes | The prio model ID | ### prio\_model ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "default_config": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "key": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "select" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "default": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] } }, "required": [ "name", "key", "type" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ] } }, "required": [ "name", "default_config" ], "title": "UpdatePrioModelRequest" }, { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "string" } } } ] } ``` ```json { "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] } } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/prio-models/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null,"default_config":{"formula":"impact * confidence / effort","inputs":[{"name":"Checkout delivery estimate","key":"example","description":null,"type":"number"}]}}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `PrioModelResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "default_config": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "key": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "select" ] }, "options": { "type": [ "array", "null" ], "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "default": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] } }, "required": [ "name", "key", "type" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "description", "default_config", "created_at", "updated_at" ], "title": "PrioModelResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] }, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-projects-project # Update project PUT /projects/{project}. Parameters, permissions, request and response schemas. `PUT /projects/{project}` Update project. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------- | -------- | -------- | -------------- | | `project` | path | Yes | The project ID | ### project ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### multipart/form-data ```json { "type": "object", "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "active", "archived" ], "title": "ProjectState" }, { "type": "null" } ] }, "name": { "type": "string", "maxLength": 255, "description": "Must be unique among projects in this Team, excluding the project being updated." }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 1024 kilobytes." }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "ProjectColor" }, { "type": "null" } ] }, "prio_model_id": { "type": [ "integer", "null" ] } }, "title": "UpdateProjectRequest" } ``` ```json { "name": "Checkout delivery estimate" } ``` ## Example request For file fields, replace the synthetic local filename with an existing file of the documented type and size. Let curl set the multipart boundary. ```bash curl --request PUT 'https://api.example.test/api/projects/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --form-string 'name=Checkout delivery estimate' \ --form 'cover=@./screenshot.png' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ProjectResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "public_id": { "type": "string" }, "state": { "anyOf": [ { "type": "string", "enum": [ "active", "archived" ], "title": "ProjectState" }, { "type": "null" } ] }, "name": { "type": "string" }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "color": { "anyOf": [ { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "ProjectColor" }, { "type": "null" } ] }, "prio_model_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "public_id", "state", "name", "cover", "color", "prio_model_id", "created_at", "updated_at" ], "title": "ProjectResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-research-collections-research-collection # Update research collection PUT /research-collections/{research\_collection}. Parameters, permissions, request and response schemas. `PUT /research-collections/{research_collection}` Update research collection. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | --------------------- | -------- | -------- | -------------------------- | | `research_collection` | path | Yes | The research collection ID | ### research\_collection ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### multipart/form-data ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 1024 kilobytes." } }, "title": "UpdateResearchCollectionRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request For file fields, replace the synthetic local filename with an existing file of the documented type and size. Let curl set the multipart boundary. ```bash curl --request PUT 'https://api.example.test/api/research-collections/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --form-string 'project_id=101' \ --form-string 'name=Checkout delivery estimate' \ --form 'cover=@./screenshot.png' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ResearchCollectionResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "cover", "created_at", "updated_at" ], "title": "ResearchCollectionResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` ### 500 The request failed. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "Error uploading file" } }, "required": [ "error" ] } ``` ```json { "error": "Error uploading file" } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-roadmap-annotations-roadmap-annotation # Update roadmap annotation PUT /roadmap-annotations/{roadmap\_annotation}. Parameters, permissions, request and response schemas. `PUT /roadmap-annotations/{roadmap_annotation}` Update roadmap annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | -------------------- | -------- | -------- | ------------------------- | | `roadmap_annotation` | path | Yes | The roadmap annotation ID | ### roadmap\_annotation ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "overlay", "marker" ], "title": "RoadmapAnnotationType" }, "annotation_type": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 255 }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] } }, "title": "UpdateRoadmapAnnotationRequest" } ``` ```json { "project_id": 101 } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/roadmap-annotations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `RoadmapAnnotationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "overlay", "marker" ], "title": "RoadmapAnnotationType" }, "annotation_type": { "type": "string" }, "label": { "type": "string" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "type", "annotation_type", "label", "start_date", "end_date", "notes", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "RoadmapAnnotationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z", "end_date": null, "notes": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-screen-annotations-screen-annotation # Update screen annotation PUT /screen-annotations/{screen\_annotation}. Parameters, permissions, request and response schemas. `PUT /screen-annotations/{screen_annotation}` Update screen annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ------------------- | -------- | -------- | ------------------------ | | `screen_annotation` | path | Yes | The screen annotation ID | ### screen\_annotation ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "note": { "type": "string", "maxLength": 65535 }, "insight_label_id": { "type": "integer" }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 }, "width": { "type": [ "integer", "null" ], "minimum": 1 }, "height": { "type": [ "integer", "null" ], "minimum": 1 }, "shape": { "type": "string", "enum": [ "point", "rect" ] }, "metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] } }, "title": "UpdateScreenAnnotationRequest" } ``` ```json { "project_id": 101 } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/screen-annotations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ScreenAnnotationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "screen_id": { "type": "integer" }, "insight_label_id": { "type": [ "integer", "null" ] }, "note": { "type": [ "string", "null" ] }, "x": { "type": [ "integer", "null" ] }, "y": { "type": [ "integer", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "shape": { "type": "string" }, "metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "screen_id", "insight_label_id", "note", "x", "y", "width", "height", "shape", "metadata", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "ScreenAnnotationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "screen_id": 101, "insight_label_id": null, "note": null, "x": null, "y": null, "width": null, "height": null, "shape": "example", "metadata": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-screens-screen # Update screen PUT /screens/{screen}. Parameters, permissions, request and response schemas. `PUT /screens/{screen}` Update screen. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | -------- | -------- | -------- | ------------- | | `screen` | path | Yes | The screen ID | ### screen ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "audience_id": { "type": [ "integer", "null" ] }, "page_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 } }, "title": "UpdateScreenRequest" } ``` ```json { "project_id": 101, "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/screens/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `ScreenResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "audience_id": { "type": [ "integer", "null" ] }, "page_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "audience_id", "page_id", "name", "description", "image", "width", "height", "created_at", "updated_at", "deleted_at" ], "title": "ScreenResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "audience_id": null, "page_id": null, "name": null, "description": null, "image": null, "width": null, "height": null, "created_at": null, "updated_at": null, "deleted_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-tags-tag # Update tag PUT /tags/{tag}. Parameters, permissions, request and response schemas. `PUT /tags/{tag}` Update tag. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ----- | -------- | -------- | ----------- | | `tag` | path | Yes | The tag ID | ### tag ```json { "type": "integer", "minimum": 1 } ``` ## Request body The request body is optional. ### application/json ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] } }, "title": "UpdateTagRequest" } ``` ```json { "name": "Checkout delivery estimate", "description": null } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/tags/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"name":"Checkout delivery estimate","description":null}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `TagResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "generic", "page", "device", "insight-detail-type", "audience" ], "title": "TagType" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "type", "description", "created_at", "updated_at" ], "title": "TagResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "type": "generic", "description": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/api/put-variations-variation # Update variation PUT /variations/{variation}. Parameters, permissions, request and response schemas. `PUT /variations/{variation}` Update variation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. ## Authentication Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication). ```json { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } ``` ## Parameters | Name | Location | Required | Description | | ----------- | -------- | -------- | ---------------- | | `variation` | path | Yes | The variation ID | ### variation ```json { "type": "integer", "minimum": 1 } ``` ## Request body A request body is required. ### application/json ```json { "type": "object", "properties": { "project_id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "traffic_percentage": { "type": "number", "minimum": 0, "maximum": 1 }, "traffic_locked": { "type": "boolean" }, "is_baseline": { "type": "boolean" } }, "required": [ "project_id", "experiment_id" ], "title": "UpdateVariationRequest" } ``` ```json { "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate" } ``` ## Example request ```bash curl --request PUT 'https://api.example.test/api/variations/1' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"project_id":101,"experiment_id":101,"name":"Checkout delivery estimate"}' ``` Examples use fictional data. Replace resource IDs and the API host with your environment’s values. ## Responses ### 200 `VariationResource` Content type: `application/json`. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "name": { "type": "string" }, "traffic_percentage": { "type": "number" }, "traffic_locked": { "type": "boolean" }, "is_baseline": { "type": "boolean" }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "array", "items": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "experiment_id", "name", "traffic_percentage", "traffic_locked", "is_baseline", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at" ], "title": "VariationResource" } }, "required": [ "data" ] } ``` ```json { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate", "traffic_percentage": 1, "traffic_locked": true, "is_baseline": true, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null } } ``` ### 401 Unauthenticated Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 402 The Team is in read-only billing mode. Content type: `application/json`. ```json { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] } ``` ```json { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } ``` ### 403 Authorization error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 404 Not found Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } ``` ```json { "message": "The request could not be completed." } ``` ### 422 Validation error Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ``` ```json { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } ``` ### 429 Rate limit exceeded. Honor Retry-After before retrying. Response headers: ```json { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } ``` Content type: `application/json`. ```json { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] } ``` ```json { "message": "Too Many Attempts." } ``` See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads. --- Source: https://conversionlab.app/docs/developer/authentication # Authenticate and choose the correct permissions Use bearer tokens with team binding, protocol abilities, roles, and plan checks. Create tokens in **Settings → Account → API Keys** while signed in. The [key guide](https://conversionlab.app/docs/team-administration/api-keys) covers creation, expiration, one-time token display, and immediate revocation by archiving. ## REST requests Send the token in the Authorization header and request JSON responses. Replace the example origin with your deployed ConversionLab API origin; it is separate from the website/docs origin. ```bash export CONVERSIONLAB_API_ORIGIN='https://api.example.test' export CONVERSIONLAB_TOKEN='YOUR_REST_TOKEN' curl --fail-with-body \ "$CONVERSIONLAB_API_ORIGIN/api/projects" \ --header "Authorization: Bearer $CONVERSIONLAB_TOKEN" \ --header 'Accept: application/json' ``` The example hostname and token are placeholders. Store real tokens in your client or server secret configuration rather than browser-delivered code or source control. Bearer API requests do not require the browser's session-login or CSRF-cookie flow. ## Abilities and roles | Key choice in the UI | Stored abilities | Purpose | | -------------------- | ----------------------- | ----------------------------------- | | REST Read only | `read` | Safe REST requests | | REST Read & Write | `read`, `write` | Reading and mutating REST requests | | MCP Read only | `mcp:read` | Reading through MCP tools | | MCP Read & Write | `mcp:read`, `mcp:write` | Reading and supported MCP mutations | REST checks `read` for safe methods and `write` for mutations; a raw `write` ability alone is not the REST read ability. Normal UI-created Read & Write keys contain both. MCP accepts its own ability family, and supported mutations require MCP write access. Token abilities do not grant an underlying user role. The authenticated user's role, project relationships, plan entitlements, and billing state are still enforced. For example, a viewer's write token does not bypass an idea's create policy, and a read-only billing account can block mutations. ## Team context Each token is bound to the team selected when it was created. Tenant data is resolved in that team's context. Supplying another team ID in the request or changing the active browser team does not retarget the token. Create a separate key for another team and use record IDs returned in that team's responses. Use `/api/user` to identify the authenticated user. Use `/api/projects` and relevant project IDs to locate tenant work. Do not treat a globally familiar numeric ID as authorization to read another team's record. ## Failed authentication An expired, revoked, or missing token can return 401. Missing abilities or team access can return 403. A REST write blocked by the team's read-only billing mode returns 402 with `error: "subscription_required"`; reading remains available. For an unexpected failure, confirm the API origin, token protocol, expiration, archive state, team membership, required role, and billing state before retrying. --- Source: https://conversionlab.app/docs/developer # Build with ConversionLab Integrate project data and reporting with your own systems using the REST API. Use the REST API to read and update supported project data and retrieve experiment reports. Start with a team-scoped API key, then choose the endpoints your integration needs. ## Connect your application [API keys and permissions](https://conversionlab.app/docs/developer/authentication) Create a team-scoped key and understand authentication, token abilities, and user roles. [API conventions](https://conversionlab.app/docs/developer/api-conventions) Understand pagination, filters, uploads, limits, and error responses. [REST API reference](https://conversionlab.app/docs/developer/api) Find supported methods, paths, request fields, response schemas, and examples. ## Supported public surface REST covers projects, research collections and screen evidence, observations, insights, learnings, ideas, experiments and variations, definitions, prioritization, numbering, attachments, comments, survey management and responses, experiment reporting and approvals, activities, the current user, and reading today's brief. Provider connection and synchronization, AI generation, team administration, billing, session authentication, and key management are configured through product workflows rather than the supported core REST contract. Public widget protocols and inbound provider callbacks are also separate from the customer integration reference. The reference documents existing runtime paths. There is no new `/v1` prefix introduced by these docs. The [OpenAPI download](https://conversionlab.app/docs/openapi.json) provides the same published REST contract in a machine-readable form. For HTTP conventions and recovery behavior see [API conventions](https://conversionlab.app/docs/developer/api-conventions). --- Source: https://conversionlab.app/docs/developer/mcp-setup # Connect an external AI client with MCP Set up Streamable HTTP, verify team context, and use the supported tool surface. ConversionLab exposes MCP at `/mcp` on the API origin using HTTP transport. MCP must be available on the deployment, and the team must have a plan other than Free. ## Create the credential Open **Settings → Account → API Keys**, select the team, and create an **MCP Read only** or **MCP Read & Write** key. Copy the token once. The creation dialog includes a Claude Code command when you create an MCP key. Use read-only access for exploration. Use Read & Write when you intend the client to create or update supported work, subject to your existing role and plan. ## Configure the client Use the API origin and an Authorization bearer header. This example matches the command offered by the app; replace the example origin and token: ```bash claude mcp add --transport http conversionlab \ https://api.example.test/mcp \ --header 'Authorization: Bearer YOUR_MCP_TOKEN' ``` For other clients, add a remote HTTP MCP server with the same URL and header using that client's supported configuration. The endpoint is `/mcp`, not `/api/mcp`. A browser session or REST-only token does not grant MCP access. ## Verify before using work-item tools 1. Call `get_mcp_context` with an empty input object. 2. Confirm the returned team, user role, token permissions, and available surface. 3. Call `list_projects` and select the intended project ID. 4. Read a relevant record before requesting a mutation. The [MCP reference](https://conversionlab.app/docs/developer/mcp) documents all 24 registered tools with inputs, outputs, examples, and permissions. Tools include search and core reads, today's available brief, and creating or updating ideas, insights, and experiments. The MCP surface does not include deletion, billing, team administration, provider configuration, private AI conversations, or daily-brief generation. Search can use AI-assisted context when team AI is available and falls back to keyword search otherwise. A search result is a lead to inspect; read the underlying entity for its full current context. ## Recover connection errors For 401, check the bearer header, token expiration, and archive state. For 403, check MCP abilities, team membership, and plan availability. A tool can also return an authorization error for a mutation the user's role, token, or read-only billing state does not allow. Read the tool's error message; MCP does not use the REST write endpoint's 402 response for these tool failures. An unavailable deployment endpoint requires checking service availability with your administrator rather than changing the request to a guessed URL. Archive the key in the app to revoke the external client's access. See [AI-readable documentation](https://conversionlab.app/docs/developer/ai-readable-docs) if the client only needs public product instructions rather than private team data. --- Source: https://conversionlab.app/docs/developer/mcp/create-experiment # create\_experiment Create an experiment. Requires mcp:write and the existing ConversionLab experiment create policy. Create an experiment. Requires mcp:write and the existing ConversionLab experiment create policy. ## Permissions ```json { "ability": "mcp:write", "role": "The existing entity create/update policy must allow this user; write ability alone is insufficient.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Project ID", "type": "integer" }, "type": { "description": "Experiment type", "enum": [ "ab_test", "multivariate_test" ], "type": "string" }, "name": { "description": "Experiment name", "maxLength": 255, "type": "string" }, "state_id": { "description": "Optional experiment state ID", "type": "integer" }, "description": { "description": "Optional description", "type": "string" }, "hypothesis": { "description": "Optional hypothesis", "type": "string" }, "insight_ids": { "description": "Optional insight IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "idea_ids": { "description": "Optional idea IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "page_ids": { "description": "Optional page IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "audience_ids": { "description": "Optional audience IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "primary_metric_id": { "description": "Optional primary metric ID", "type": "integer" }, "secondary_metric_ids": { "description": "Optional secondary metric IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "guardrail_metric_ids": { "description": "Optional guardrail metric IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "start_date": { "description": "Optional start date", "type": "string" }, "end_date": { "description": "Optional end date", "type": "string" } }, "type": "object", "required": [ "project_id", "type", "name" ] } ``` ## Output ```json { "type": "object", "properties": { "created": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "state_id": { "type": [ "integer", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "ab_test", "multivariate_test", null ] }, "result": { "type": [ "string", "null" ], "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other", null ] }, "decision": { "type": [ "string", "null" ], "enum": [ "implement", "rollout", "retest", "iterate", "reject", null ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "project": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "hypothesis": { "type": [ "string", "null" ] }, "learning": { "type": [ "string", "null" ] }, "stop_reason": { "type": [ "string", "null" ], "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other", null ] }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "primary_metric": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "secondary_metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "guardrail_metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "ideas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "project_id", "name", "state_id", "primary_metric_id", "type", "result", "decision", "start_date", "end_date", "created_at", "updated_at", "description", "project", "hypothesis", "learning", "stop_reason", "state", "primary_metric", "secondary_metrics", "guardrail_metrics", "audiences", "ideas", "insights", "pages" ] } }, "required": [ "created", "data" ] } ``` ## Examples ### Request arguments ```json { "project_id": 1, "type": "ab_test", "name": "Show delivery estimate" } ``` ### Result ```json { "created": true, "data": { "id": 101, "project_id": 1, "state_id": null, "primary_metric_id": null, "name": "Show delivery estimate", "type": "ab_test", "result": null, "decision": null, "start_date": null, "end_date": null, "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00", "description": null, "hypothesis": null, "learning": null, "stop_reason": null, "project": null, "state": null, "primary_metric": null, "secondary_metrics": [], "guardrail_metrics": [], "audiences": [], "ideas": [], "insights": [], "pages": [] } } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/create-idea # create\_idea Create an idea. Requires mcp:write and the existing ConversionLab idea create policy. Create an idea. Requires mcp:write and the existing ConversionLab idea create policy. ## Permissions ```json { "ability": "mcp:write", "role": "The existing entity create/update policy must allow this user; write ability alone is insufficient.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Project ID", "type": "integer" }, "name": { "description": "Idea name", "maxLength": 255, "type": "string" }, "state_id": { "description": "Optional idea state ID", "type": "integer" }, "source": { "description": "Optional source type", "type": "string" }, "source_name": { "description": "Optional source label", "type": "string" }, "description": { "description": "Optional description", "type": "string" }, "hypothesis": { "description": "Optional hypothesis", "type": "string" }, "audience_ids": { "description": "Optional audience IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "experiment_ids": { "description": "Optional experiment IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "insight_ids": { "description": "Optional insight IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "metric_ids": { "description": "Optional metric IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "page_ids": { "description": "Optional page IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "priority_values": { "description": "Optional prioritization values keyed by input variable, for example {\"impact\": 5, \"confidence\": 8, \"effort\": 2}", "type": [ "object", "null" ] } }, "type": "object", "required": [ "project_id", "name" ] } ``` ## Output ```json { "type": "object", "properties": { "created": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "state_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ], "enum": [ "audit", "insight", "experiment", "form", "api", null ] }, "source_name": { "type": [ "string", "null" ] }, "priority_score": { "type": [ "number", "string", "null" ], "description": "A decimal may be serialized as a string." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "project": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "hypothesis": { "type": [ "string", "null" ] }, "priority_values": { "type": [ "object", "array", "null" ], "additionalProperties": true, "items": true, "description": "Stored JSON values, usually keyed by the prioritization model variable." }, "priority_details": { "type": [ "object", "array", "null" ], "additionalProperties": true, "items": true }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "project_id", "name", "state_id", "source", "source_name", "priority_score", "created_at", "updated_at", "description", "project", "hypothesis", "priority_values", "priority_details", "state", "audiences", "experiments", "insights", "metrics", "pages" ] } }, "required": [ "created", "data" ] } ``` ## Examples ### Request arguments ```json { "project_id": 1, "name": "Explain delivery times at checkout" } ``` ### Result ```json { "created": true, "data": { "id": 101, "project_id": 1, "state_id": null, "name": "Explain delivery times at checkout", "source": "audit", "source_name": null, "priority_score": null, "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00", "description": null, "hypothesis": null, "priority_values": null, "priority_details": null, "project": null, "state": null, "audiences": [], "experiments": [], "insights": [], "metrics": [], "pages": [] } } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/create-insight # create\_insight Create an insight. Requires mcp:write and the existing ConversionLab insight create policy. Create an insight. Requires mcp:write and the existing ConversionLab insight create policy. ## Permissions ```json { "ability": "mcp:write", "role": "The existing entity create/update policy must allow this user; write ability alone is insufficient.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Project ID", "type": "integer" }, "name": { "description": "Insight name", "maxLength": 255, "type": "string" }, "source": { "description": "Optional source", "type": "string" }, "description": { "description": "Optional description", "type": "string" }, "research_collection_id": { "description": "Optional research collection ID", "type": "integer" }, "insight_label_id": { "description": "Optional insight label ID", "type": "integer" }, "audience_ids": { "description": "Optional audience IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "experiment_ids": { "description": "Optional experiment IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "idea_ids": { "description": "Optional idea IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "observation_ids": { "description": "Optional Observation IDs supporting this Insight", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "page_ids": { "description": "Optional page IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] } }, "type": "object", "required": [ "project_id", "name" ] } ``` ## Output ```json { "type": "object", "properties": { "created": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "insight_label_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "project": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "ideas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "project_id", "name", "insight_label_id", "source", "created_at", "updated_at", "description", "project", "label", "audiences", "experiments", "ideas", "pages" ] } }, "required": [ "created", "data" ] } ``` ## Examples ### Request arguments ```json { "project_id": 1, "name": "Delivery uncertainty stops checkout" } ``` ### Result ```json { "created": true, "data": { "id": 101, "project_id": 1, "insight_label_id": null, "name": "Delivery uncertainty stops checkout", "source": "Customer research", "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00", "description": null, "project": null, "label": null, "audiences": [], "experiments": [], "ideas": [], "pages": [] } } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/get-experiment # get\_experiment Get a full experiment record with linked summaries and metrics. Get a full experiment record with linked summaries and metrics. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "experiment_id": { "description": "Experiment ID", "type": "integer" } }, "type": "object", "required": [ "experiment_id" ] } ``` ## Output ```json { "type": "object", "properties": { "found": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "state_id": { "type": [ "integer", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "ab_test", "multivariate_test", null ] }, "result": { "type": [ "string", "null" ], "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other", null ] }, "decision": { "type": [ "string", "null" ], "enum": [ "implement", "rollout", "retest", "iterate", "reject", null ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "project": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "hypothesis": { "type": [ "string", "null" ] }, "learning": { "type": [ "string", "null" ] }, "stop_reason": { "type": [ "string", "null" ], "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other", null ] }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "primary_metric": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "secondary_metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "guardrail_metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "ideas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "project_id", "name", "state_id", "primary_metric_id", "type", "result", "decision", "start_date", "end_date", "created_at", "updated_at", "description", "project", "hypothesis", "learning", "stop_reason", "state", "primary_metric", "secondary_metrics", "guardrail_metrics", "audiences", "ideas", "insights", "pages" ] }, { "type": "null" } ] } }, "required": [ "found", "data" ] } ``` ## Examples ### Request arguments ```json { "experiment_id": 101 } ``` ### Result ```json { "found": true, "data": { "id": 101, "project_id": 1, "state_id": null, "primary_metric_id": null, "name": "Show delivery estimate", "type": "ab_test", "result": null, "decision": null, "start_date": null, "end_date": null, "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00", "description": null, "hypothesis": null, "learning": null, "stop_reason": null, "project": null, "state": null, "primary_metric": null, "secondary_metrics": [], "guardrail_metrics": [], "audiences": [], "ideas": [], "insights": [], "pages": [] } } ``` ### Request arguments ```json { "experiment_id": 101 } ``` ### Result ```json { "found": false, "data": null } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/get-idea # get\_idea Get a full idea record with linked summaries. Get a full idea record with linked summaries. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "idea_id": { "description": "Idea ID", "type": "integer" } }, "type": "object", "required": [ "idea_id" ] } ``` ## Output ```json { "type": "object", "properties": { "found": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "state_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ], "enum": [ "audit", "insight", "experiment", "form", "api", null ] }, "source_name": { "type": [ "string", "null" ] }, "priority_score": { "type": [ "number", "string", "null" ], "description": "A decimal may be serialized as a string." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "project": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "hypothesis": { "type": [ "string", "null" ] }, "priority_values": { "type": [ "object", "array", "null" ], "additionalProperties": true, "items": true, "description": "Stored JSON values, usually keyed by the prioritization model variable." }, "priority_details": { "type": [ "object", "array", "null" ], "additionalProperties": true, "items": true }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "project_id", "name", "state_id", "source", "source_name", "priority_score", "created_at", "updated_at", "description", "project", "hypothesis", "priority_values", "priority_details", "state", "audiences", "experiments", "insights", "metrics", "pages" ] }, { "type": "null" } ] } }, "required": [ "found", "data" ] } ``` ## Examples ### Request arguments ```json { "idea_id": 101 } ``` ### Result ```json { "found": true, "data": { "id": 101, "project_id": 1, "state_id": null, "name": "Explain delivery times at checkout", "source": "audit", "source_name": null, "priority_score": null, "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00", "description": null, "hypothesis": null, "priority_values": null, "priority_details": null, "project": null, "state": null, "audiences": [], "experiments": [], "insights": [], "metrics": [], "pages": [] } } ``` ### Request arguments ```json { "idea_id": 101 } ``` ### Result ```json { "found": false, "data": null } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/get-insight # get\_insight Get a full insight record with linked summaries. Get a full insight record with linked summaries. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "insight_id": { "description": "Insight ID", "type": "integer" } }, "type": "object", "required": [ "insight_id" ] } ``` ## Output ```json { "type": "object", "properties": { "found": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "insight_label_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "project": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "ideas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "project_id", "name", "insight_label_id", "source", "created_at", "updated_at", "description", "project", "label", "audiences", "experiments", "ideas", "pages" ] }, { "type": "null" } ] } }, "required": [ "found", "data" ] } ``` ## Examples ### Request arguments ```json { "insight_id": 101 } ``` ### Result ```json { "found": true, "data": { "id": 101, "project_id": 1, "insight_label_id": null, "name": "Delivery uncertainty stops checkout", "source": "Customer research", "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00", "description": null, "project": null, "label": null, "audiences": [], "experiments": [], "ideas": [], "pages": [] } } ``` ### Request arguments ```json { "insight_id": 101 } ``` ### Result ```json { "found": false, "data": null } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/get-mcp-context # get\_mcp\_context Describe the authenticated ConversionLab team, user role, MCP token permissions, and available MCP surface. Describe the authenticated ConversionLab team, user role, MCP token permissions, and available MCP surface. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "type": "object", "properties": {} } ``` ## Output ```json { "type": "object", "properties": { "team": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "ai_available": { "type": "boolean" }, "billing_mode": { "type": "string" } }, "required": [ "id", "name", "slug", "ai_available", "billing_mode" ] }, { "type": "null" } ] }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role" ] }, { "type": "null" } ] }, "token": { "type": "object", "properties": { "abilities": { "type": "array", "items": { "type": "string" } }, "can_read": { "type": "boolean" }, "can_write": { "type": "boolean" } }, "required": [ "abilities", "can_read", "can_write" ] }, "surface": { "type": "object", "properties": { "read_tools": { "type": "array", "items": { "type": "string" } }, "write_tools": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "array", "items": { "type": "string" } } }, "required": [ "read_tools", "write_tools", "excluded" ] } }, "required": [ "team", "user", "token", "surface" ] } ``` ## Examples ### Request arguments ```json {} ``` ### Result ```json { "team": { "id": 1, "name": "Fictional Store", "slug": "fictional-store", "ai_available": false, "billing_mode": "active" }, "user": { "id": 1, "name": "Alex Example", "email": "alex@example.com", "role": "owner" }, "token": { "abilities": [ "mcp:read" ], "can_read": true, "can_write": false }, "surface": { "read_tools": [ "list_projects", "get_idea" ], "write_tools": [ "create_idea", "update_idea" ], "excluded": [ "billing", "team_admin", "deletes" ] } } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/get-metric # get\_metric Get a metric by ID. Get a metric by ID. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "metric_id": { "description": "Metric ID", "type": "integer" } }, "type": "object", "required": [ "metric_id" ] } ``` ## Output ```json { "type": "object", "properties": { "found": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session", null ] }, "winning_direction": { "type": [ "string", "null" ], "enum": [ "increasing", "decreasing", null ] } }, "required": [ "id", "project_id", "name", "description", "type", "winning_direction" ] }, { "type": "null" } ] } }, "required": [ "found", "data" ] } ``` ## Examples ### Request arguments ```json { "metric_id": 101 } ``` ### Result ```json { "found": true, "data": { "id": 101, "project_id": 1, "name": "Checkout conversion", "description": null, "type": "average-per-user", "winning_direction": "increasing" } } ``` ### Request arguments ```json { "metric_id": 101 } ``` ### Result ```json { "found": false, "data": null } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/get-project # get\_project Get a project by ID. Get a project by ID. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Project ID", "type": "integer" } }, "type": "object", "required": [ "project_id" ] } ``` ## Output ```json { "type": "object", "properties": { "found": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "state": { "type": [ "string", "null" ], "enum": [ "active", "archived", null ] }, "color": { "type": [ "string", "null" ], "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose", null ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "state", "color", "created_at", "updated_at" ] }, { "type": "null" } ] } }, "required": [ "found", "data" ] } ``` ## Examples ### Request arguments ```json { "project_id": 1 } ``` ### Result ```json { "found": true, "data": { "id": 101, "name": "Fictional Store", "state": "active", "color": "gray", "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00" } } ``` ### Request arguments ```json { "project_id": 1 } ``` ### Result ```json { "found": false, "data": null } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/get-today-daily-brief # get\_today\_daily\_brief Return today's retained daily brief if one already exists. This never generates a new brief. Return today's retained daily brief if one already exists. This never generates a new brief. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "type": "object", "properties": {} } ``` ## Output ```json { "type": "object", "properties": { "found": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "brief_date": { "type": [ "string", "null" ], "format": "date" }, "content": { "type": [ "string", "null" ] }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "viewed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "brief_date", "content", "generated_at", "viewed_at" ] }, { "type": "null" } ] } }, "required": [ "found", "data" ] } ``` ## Examples ### Request arguments ```json {} ``` ### Result ```json { "found": true, "data": { "id": 101, "brief_date": "2026-01-15", "content": "## Today\\nReview the delivery estimate experiment.", "generated_at": "2026-01-15T12:00:00+00:00", "viewed_at": null } } ``` ### Request arguments ```json {} ``` ### Result ```json { "found": false, "data": null } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp # MCP tool reference Inputs, outputs, permissions, and examples for every registered ConversionLab MCP tool. Connect external AI tools with [MCP setup](https://conversionlab.app/docs/developer/mcp-setup). MCP exposes a smaller surface than the REST API. Examples use fictional data. - [`create_experiment`](https://conversionlab.app/docs/developer/mcp/create-experiment) — Create an experiment. Requires mcp:write and the existing ConversionLab experiment create policy. - [`create_idea`](https://conversionlab.app/docs/developer/mcp/create-idea) — Create an idea. Requires mcp:write and the existing ConversionLab idea create policy. - [`create_insight`](https://conversionlab.app/docs/developer/mcp/create-insight) — Create an insight. Requires mcp:write and the existing ConversionLab insight create policy. - [`get_experiment`](https://conversionlab.app/docs/developer/mcp/get-experiment) — Get a full experiment record with linked summaries and metrics. - [`get_idea`](https://conversionlab.app/docs/developer/mcp/get-idea) — Get a full idea record with linked summaries. - [`get_insight`](https://conversionlab.app/docs/developer/mcp/get-insight) — Get a full insight record with linked summaries. - [`get_mcp_context`](https://conversionlab.app/docs/developer/mcp/get-mcp-context) — Describe the authenticated ConversionLab team, user role, MCP token permissions, and available MCP surface. - [`get_metric`](https://conversionlab.app/docs/developer/mcp/get-metric) — Get a metric by ID. - [`get_project`](https://conversionlab.app/docs/developer/mcp/get-project) — Get a project by ID. - [`get_today_daily_brief`](https://conversionlab.app/docs/developer/mcp/get-today-daily-brief) — Return today's retained daily brief if one already exists. This never generates a new brief. - [`list_audiences`](https://conversionlab.app/docs/developer/mcp/list-audiences) — List configured audiences, optionally filtered by project. - [`list_experiment_states`](https://conversionlab.app/docs/developer/mcp/list-experiment-states) — List experiment states, optionally filtered by project. - [`list_experiments`](https://conversionlab.app/docs/developer/mcp/list-experiments) — List experiments, optionally filtered by project, state, type, or metric. - [`list_idea_states`](https://conversionlab.app/docs/developer/mcp/list-idea-states) — List idea states, optionally filtered by project. - [`list_ideas`](https://conversionlab.app/docs/developer/mcp/list-ideas) — List ideas, optionally filtered by project or state. - [`list_insight_labels`](https://conversionlab.app/docs/developer/mcp/list-insight-labels) — List insight labels, optionally filtered by project. - [`list_insights`](https://conversionlab.app/docs/developer/mcp/list-insights) — List insights, optionally filtered by project or label. - [`list_metrics`](https://conversionlab.app/docs/developer/mcp/list-metrics) — List metrics, optionally filtered by project. - [`list_pages`](https://conversionlab.app/docs/developer/mcp/list-pages) — List configured pages, optionally filtered by project. - [`list_projects`](https://conversionlab.app/docs/developer/mcp/list-projects) — List projects in the authenticated team. - [`search_conversionlab`](https://conversionlab.app/docs/developer/mcp/search-conversionlab) — Search ConversionLab projects, ideas, insights, experiments, metrics, pages, and audiences. Uses semantic search only when team AI is available, otherwise falls back to keyword search. - [`update_experiment`](https://conversionlab.app/docs/developer/mcp/update-experiment) — Update an experiment. Requires mcp:write and the existing ConversionLab experiment update policy. - [`update_idea`](https://conversionlab.app/docs/developer/mcp/update-idea) — Update an idea. Requires mcp:write and the existing ConversionLab idea update policy. - [`update_insight`](https://conversionlab.app/docs/developer/mcp/update-insight) — Update an insight. Requires mcp:write and the existing ConversionLab insight update policy. --- Source: https://conversionlab.app/docs/developer/mcp/list-audiences # list\_audiences List configured audiences, optionally filtered by project. List configured audiences, optionally filtered by project. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Optional project ID filter", "type": "integer" }, "limit": { "description": "Result limit; defaults to 50 and is clamped to 1–100", "type": "integer" } }, "type": "object" } ``` ## Output ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "required": [ "id", "project_id", "name", "description" ] } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "limit" ] } }, "required": [ "data", "meta" ] } ``` ## Examples ### Request arguments ```json { "limit": 10 } ``` ### Result ```json { "data": [ { "id": 101, "project_id": 1, "name": "New visitors", "description": null } ], "meta": { "limit": 10 } } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/list-experiment-states # list\_experiment\_states List experiment states, optionally filtered by project. List experiment states, optionally filtered by project. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Optional project ID filter", "type": "integer" } }, "type": "object" } ``` ## Output ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ], "enum": [ "draft", "live", "paused", "finished", "archived", null ] }, "order": { "type": [ "integer", "null" ] } }, "required": [ "id", "project_id", "name", "description", "category", "order" ] } } }, "required": [ "data" ] } ``` ## Examples ### Request arguments ```json {} ``` ### Result ```json { "data": [ { "id": 101, "project_id": 1, "name": "Planned", "description": null, "category": null, "order": 1 } ] } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/list-experiments # list\_experiments List experiments, optionally filtered by project, state, type, or metric. List experiments, optionally filtered by project, state, type, or metric. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Optional project ID filter", "type": "integer" }, "state_id": { "description": "Optional experiment state ID filter", "type": "integer" }, "state": { "description": "Optional experiment state name filter", "type": "string" }, "type": { "description": "Optional experiment type filter", "type": "string" }, "metric_id": { "description": "Optional metric ID filter", "type": "integer" }, "limit": { "description": "Result limit; defaults to 50 and is clamped to 1–100", "type": "integer" } }, "type": "object" } ``` ## Output ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "state_id": { "type": [ "integer", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "ab_test", "multivariate_test", null ] }, "result": { "type": [ "string", "null" ], "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other", null ] }, "decision": { "type": [ "string", "null" ], "enum": [ "implement", "rollout", "retest", "iterate", "reject", null ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "state_id", "primary_metric_id", "type", "result", "decision", "start_date", "end_date", "created_at", "updated_at" ] } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "limit" ] } }, "required": [ "data", "meta" ] } ``` ## Examples ### Request arguments ```json { "limit": 10 } ``` ### Result ```json { "data": [ { "id": 101, "project_id": 1, "state_id": null, "primary_metric_id": null, "name": "Show delivery estimate", "type": "ab_test", "result": null, "decision": null, "start_date": null, "end_date": null, "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00" } ], "meta": { "limit": 10 } } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/list-idea-states # list\_idea\_states List idea states, optionally filtered by project. List idea states, optionally filtered by project. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Optional project ID filter", "type": "integer" } }, "type": "object" } ``` ## Output ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "order": { "type": [ "integer", "null" ] } }, "required": [ "id", "project_id", "name", "description", "color", "order" ] } } }, "required": [ "data" ] } ``` ## Examples ### Request arguments ```json {} ``` ### Result ```json { "data": [ { "id": 101, "project_id": 1, "name": "Backlog", "description": null, "color": "gray", "order": 1 } ] } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/list-ideas # list\_ideas List ideas, optionally filtered by project or state. List ideas, optionally filtered by project or state. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Optional project ID filter", "type": "integer" }, "state_id": { "description": "Optional idea state ID filter", "type": "integer" }, "state": { "description": "Optional idea state name filter", "type": "string" }, "limit": { "description": "Result limit; defaults to 50 and is clamped to 1–100", "type": "integer" } }, "type": "object" } ``` ## Output ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "state_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ], "enum": [ "audit", "insight", "experiment", "form", "api", null ] }, "source_name": { "type": [ "string", "null" ] }, "priority_score": { "type": [ "number", "string", "null" ], "description": "A decimal may be serialized as a string." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "state_id", "source", "source_name", "priority_score", "created_at", "updated_at" ] } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "limit" ] } }, "required": [ "data", "meta" ] } ``` ## Examples ### Request arguments ```json { "limit": 10 } ``` ### Result ```json { "data": [ { "id": 101, "project_id": 1, "state_id": null, "name": "Explain delivery times at checkout", "source": "audit", "source_name": null, "priority_score": null, "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00" } ], "meta": { "limit": 10 } } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/list-insight-labels # list\_insight\_labels List insight labels, optionally filtered by project. List insight labels, optionally filtered by project. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Optional project ID filter", "type": "integer" } }, "type": "object" } ``` ## Output ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "order": { "type": [ "integer", "null" ] } }, "required": [ "id", "project_id", "name", "color", "order" ] } } }, "required": [ "data" ] } ``` ## Examples ### Request arguments ```json {} ``` ### Result ```json { "data": [ { "id": 101, "project_id": 1, "name": "Usability", "color": "gray", "order": 1 } ] } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/list-insights # list\_insights List insights, optionally filtered by project or label. List insights, optionally filtered by project or label. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Optional project ID filter", "type": "integer" }, "insight_label_id": { "description": "Optional insight label ID filter", "type": "integer" }, "limit": { "description": "Result limit; defaults to 50 and is clamped to 1–100", "type": "integer" } }, "type": "object" } ``` ## Output ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "insight_label_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "insight_label_id", "source", "created_at", "updated_at" ] } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "limit" ] } }, "required": [ "data", "meta" ] } ``` ## Examples ### Request arguments ```json { "limit": 10 } ``` ### Result ```json { "data": [ { "id": 101, "project_id": 1, "insight_label_id": null, "name": "Delivery uncertainty stops checkout", "source": "Customer research", "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00" } ], "meta": { "limit": 10 } } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/list-metrics # list\_metrics List metrics, optionally filtered by project. List metrics, optionally filtered by project. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Optional project ID filter", "type": "integer" }, "limit": { "description": "Result limit; defaults to 50 and is clamped to 1–100", "type": "integer" } }, "type": "object" } ``` ## Output ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session", null ] }, "winning_direction": { "type": [ "string", "null" ], "enum": [ "increasing", "decreasing", null ] } }, "required": [ "id", "project_id", "name", "description", "type", "winning_direction" ] } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "limit" ] } }, "required": [ "data", "meta" ] } ``` ## Examples ### Request arguments ```json { "limit": 10 } ``` ### Result ```json { "data": [ { "id": 101, "project_id": 1, "name": "Checkout conversion", "description": null, "type": "average-per-user", "winning_direction": "increasing" } ], "meta": { "limit": 10 } } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/list-pages # list\_pages List configured pages, optionally filtered by project. List configured pages, optionally filtered by project. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "project_id": { "description": "Optional project ID filter", "type": "integer" }, "limit": { "description": "Result limit; defaults to 50 and is clamped to 1–100", "type": "integer" } }, "type": "object" } ``` ## Output ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "required": [ "id", "project_id", "name", "description" ] } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "limit" ] } }, "required": [ "data", "meta" ] } ``` ## Examples ### Request arguments ```json { "limit": 10 } ``` ### Result ```json { "data": [ { "id": 101, "project_id": 1, "name": "Checkout", "description": null } ], "meta": { "limit": 10 } } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/list-projects # list\_projects List projects in the authenticated team. List projects in the authenticated team. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "limit": { "description": "Result limit; defaults to 50 and is clamped to 1–100", "type": "integer" } }, "type": "object" } ``` ## Output ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "state": { "type": [ "string", "null" ], "enum": [ "active", "archived", null ] }, "color": { "type": [ "string", "null" ], "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose", null ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "state", "color", "created_at", "updated_at" ] } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "limit" ] } }, "required": [ "data", "meta" ] } ``` ## Examples ### Request arguments ```json { "limit": 10 } ``` ### Result ```json { "data": [ { "id": 101, "name": "Fictional Store", "state": "active", "color": "gray", "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00" } ], "meta": { "limit": 10 } } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/search-conversionlab # search\_conversionlab Search ConversionLab projects, ideas, insights, experiments, metrics, pages, and audiences. Uses semantic search only when team AI is available, otherwise falls back to keyword search. Search ConversionLab projects, ideas, insights, experiments, metrics, pages, and audiences. Uses semantic search only when team AI is available, otherwise falls back to keyword search. ## Permissions ```json { "ability": "mcp:read or mcp:write", "role": "Team membership and applicable entity view policies are required.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "query": { "description": "Search query", "type": "string" }, "project_id": { "description": "Optional project ID filter", "type": "integer" }, "state": { "description": "Optional idea or experiment state name filter", "type": "string" }, "metric_id": { "description": "Optional metric ID filter", "type": "integer" }, "limit": { "description": "Result limit; defaults to 10 and is clamped to 1–10", "type": "integer" } }, "type": "object", "required": [ "query" ] } ``` ## Output ```json { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "keyword", "semantic" ] }, "fallback_reason": { "type": [ "string", "null" ], "enum": [ "empty_query", "ai_unavailable", "ai_rate_limited", "semantic_failed", null ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project", "idea", "insight", "observation", "experiment", "metric", "page", "audience" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "content": { "type": "string" }, "score": { "type": [ "number", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "state": { "type": [ "string", "null" ] }, "section": { "type": "string" }, "project": { "type": [ "string", "null" ] } }, "required": [ "type", "id", "name", "content", "score", "project_id", "state" ] } } }, "required": [ "mode", "fallback_reason", "results" ] } ``` ## Examples ### Request arguments ```json { "query": "delivery", "project_id": 1, "limit": 5 } ``` ### Result ```json { "mode": "keyword", "fallback_reason": "ai_unavailable", "results": [ { "type": "idea", "id": 101, "name": "Explain delivery times at checkout", "content": "State the delivery estimate before payment.", "score": null, "project_id": 1, "state": "Backlog" } ] } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/update-experiment # update\_experiment Update an experiment. Requires mcp:write and the existing ConversionLab experiment update policy. Update an experiment. Requires mcp:write and the existing ConversionLab experiment update policy. ## Permissions ```json { "ability": "mcp:write", "role": "The existing entity create/update policy must allow this user; write ability alone is insufficient.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "experiment_id": { "description": "Experiment ID", "type": "integer" }, "project_id": { "description": "Optional new project ID", "type": "integer" }, "type": { "description": "Optional experiment type", "enum": [ "ab_test", "multivariate_test" ], "type": "string" }, "name": { "description": "Optional experiment name", "maxLength": 255, "type": "string" }, "state_id": { "description": "Optional experiment state ID", "type": "integer" }, "description": { "description": "Optional description", "type": "string" }, "hypothesis": { "description": "Optional hypothesis", "type": "string" }, "insight_ids": { "description": "Optional replacement insight IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "idea_ids": { "description": "Optional replacement idea IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "page_ids": { "description": "Optional replacement page IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "audience_ids": { "description": "Optional replacement audience IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "primary_metric_id": { "description": "Optional primary metric ID", "type": "integer" }, "secondary_metric_ids": { "description": "Optional replacement secondary metric IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "guardrail_metric_ids": { "description": "Optional replacement guardrail metric IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "start_date": { "description": "Optional start date", "type": "string" }, "end_date": { "description": "Optional end date", "type": "string" } }, "type": "object", "required": [ "experiment_id" ] } ``` ## Output ```json { "type": "object", "properties": { "updated": { "type": "boolean" }, "found": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "state_id": { "type": [ "integer", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "ab_test", "multivariate_test", null ] }, "result": { "type": [ "string", "null" ], "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other", null ] }, "decision": { "type": [ "string", "null" ], "enum": [ "implement", "rollout", "retest", "iterate", "reject", null ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "project": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "hypothesis": { "type": [ "string", "null" ] }, "learning": { "type": [ "string", "null" ] }, "stop_reason": { "type": [ "string", "null" ], "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other", null ] }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "primary_metric": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "secondary_metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "guardrail_metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "ideas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "project_id", "name", "state_id", "primary_metric_id", "type", "result", "decision", "start_date", "end_date", "created_at", "updated_at", "description", "project", "hypothesis", "learning", "stop_reason", "state", "primary_metric", "secondary_metrics", "guardrail_metrics", "audiences", "ideas", "insights", "pages" ] }, { "type": "null" } ] } }, "required": [ "updated", "found", "data" ] } ``` ## Examples ### Request arguments ```json { "experiment_id": 101, "name": "Show delivery estimate" } ``` ### Result ```json { "updated": true, "found": true, "data": { "id": 101, "project_id": 1, "state_id": null, "primary_metric_id": null, "name": "Show delivery estimate", "type": "ab_test", "result": null, "decision": null, "start_date": null, "end_date": null, "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00", "description": null, "hypothesis": null, "learning": null, "stop_reason": null, "project": null, "state": null, "primary_metric": null, "secondary_metrics": [], "guardrail_metrics": [], "audiences": [], "ideas": [], "insights": [], "pages": [] } } ``` ### Request arguments ```json { "experiment_id": 101, "name": "Show delivery estimate" } ``` ### Result ```json { "updated": false, "found": false, "data": null } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/update-idea # update\_idea Update an idea. Requires mcp:write and the existing ConversionLab idea update policy. Update an idea. Requires mcp:write and the existing ConversionLab idea update policy. ## Permissions ```json { "ability": "mcp:write", "role": "The existing entity create/update policy must allow this user; write ability alone is insufficient.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "idea_id": { "description": "Idea ID", "type": "integer" }, "project_id": { "description": "Optional new project ID", "type": "integer" }, "name": { "description": "Optional idea name", "maxLength": 255, "type": "string" }, "state_id": { "description": "Optional idea state ID", "type": "integer" }, "source": { "description": "Optional source type", "type": "string" }, "description": { "description": "Optional description", "type": "string" }, "hypothesis": { "description": "Optional hypothesis", "type": "string" }, "audience_ids": { "description": "Optional replacement audience IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "experiment_ids": { "description": "Optional replacement experiment IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "insight_ids": { "description": "Optional replacement insight IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "metric_ids": { "description": "Optional replacement metric IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "page_ids": { "description": "Optional replacement page IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "priority_values": { "description": "Optional prioritization values keyed by input variable, for example {\"impact\": 5, \"confidence\": 8, \"effort\": 2}", "type": [ "object", "null" ] } }, "type": "object", "required": [ "idea_id" ] } ``` ## Output ```json { "type": "object", "properties": { "updated": { "type": "boolean" }, "found": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "state_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ], "enum": [ "audit", "insight", "experiment", "form", "api", null ] }, "source_name": { "type": [ "string", "null" ] }, "priority_score": { "type": [ "number", "string", "null" ], "description": "A decimal may be serialized as a string." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "project": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "hypothesis": { "type": [ "string", "null" ] }, "priority_values": { "type": [ "object", "array", "null" ], "additionalProperties": true, "items": true, "description": "Stored JSON values, usually keyed by the prioritization model variable." }, "priority_details": { "type": [ "object", "array", "null" ], "additionalProperties": true, "items": true }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "project_id", "name", "state_id", "source", "source_name", "priority_score", "created_at", "updated_at", "description", "project", "hypothesis", "priority_values", "priority_details", "state", "audiences", "experiments", "insights", "metrics", "pages" ] }, { "type": "null" } ] } }, "required": [ "updated", "found", "data" ] } ``` ## Examples ### Request arguments ```json { "idea_id": 101, "name": "Explain delivery times at checkout" } ``` ### Result ```json { "updated": true, "found": true, "data": { "id": 101, "project_id": 1, "state_id": null, "name": "Explain delivery times at checkout", "source": "audit", "source_name": null, "priority_score": null, "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00", "description": null, "hypothesis": null, "priority_values": null, "priority_details": null, "project": null, "state": null, "audiences": [], "experiments": [], "insights": [], "metrics": [], "pages": [] } } ``` ### Request arguments ```json { "idea_id": 101, "name": "Explain delivery times at checkout" } ``` ### Result ```json { "updated": false, "found": false, "data": null } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/developer/mcp/update-insight # update\_insight Update an insight. Requires mcp:write and the existing ConversionLab insight update policy. Update an insight. Requires mcp:write and the existing ConversionLab insight update policy. ## Permissions ```json { "ability": "mcp:write", "role": "The existing entity create/update policy must allow this user; write ability alone is insufficient.", "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.", "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant." } ``` ## Input ```json { "properties": { "insight_id": { "description": "Insight ID", "type": "integer" }, "project_id": { "description": "Optional new project ID", "type": "integer" }, "name": { "description": "Optional insight name", "maxLength": 255, "type": "string" }, "source": { "description": "Optional source", "type": "string" }, "description": { "description": "Optional description", "type": "string" }, "research_collection_id": { "description": "Optional research collection ID", "type": "integer" }, "insight_label_id": { "description": "Optional insight label ID", "type": "integer" }, "audience_ids": { "description": "Optional replacement audience IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "experiment_ids": { "description": "Optional replacement experiment IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "idea_ids": { "description": "Optional replacement idea IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "page_ids": { "description": "Optional replacement page IDs", "items": { "type": "integer" }, "type": [ "array", "null" ] } }, "type": "object", "required": [ "insight_id" ] } ``` ## Output ```json { "type": "object", "properties": { "updated": { "type": "boolean" }, "found": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "insight_label_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "project": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "experiments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "ideas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "project_id", "name", "insight_label_id", "source", "created_at", "updated_at", "description", "project", "label", "audiences", "experiments", "ideas", "pages" ] }, { "type": "null" } ] } }, "required": [ "updated", "found", "data" ] } ``` ## Examples ### Request arguments ```json { "insight_id": 101, "name": "Delivery uncertainty stops checkout" } ``` ### Result ```json { "updated": true, "found": true, "data": { "id": 101, "project_id": 1, "insight_label_id": null, "name": "Delivery uncertainty stops checkout", "source": "Customer research", "created_at": "2026-01-15T12:00:00+00:00", "updated_at": "2026-01-15T12:00:00+00:00", "description": null, "project": null, "label": null, "audiences": [], "experiments": [], "ideas": [], "pages": [] } } ``` ### Request arguments ```json { "insight_id": 101, "name": "Delivery uncertainty stops checkout" } ``` ### Result ```json { "updated": false, "found": false, "data": null } ``` ## Errors ```json [ { "status": 401, "description": "Missing, expired, or revoked bearer token." }, { "status": 403, "description": "Missing MCP ability, team membership, plan entitlement, or user permission." }, { "status": 404, "description": "The MCP server is disabled." }, { "status": 429, "description": "Rate limited; honor Retry-After before retrying." }, { "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call." } ] ``` An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication). --- Source: https://conversionlab.app/docs/experiments/analytics # Review experimentation activity in Analytics Use signals, execution balance, and detailed operational metrics. Open **Analytics** to understand the flow of research and experimentation work. It summarizes the records and lifecycle activity tracked in ConversionLab. ## Start with Signals The **Signals** tab highlights work such as insights and ideas created, experiments created, started and finished, and the average time from idea to experiment. Review comparisons with the prior period alongside the current totals. **Weekly execution balance** compares experiments started and finished. It helps identify weeks when work entering the process exceeds work completed. These counts describe program activity; they are separate from an experiment's conversion rate or business impact. ## Inspect Details Open **Details** to review operational metrics and the daily, weekly, or monthly tables. Use the rows to check which time periods explain a headline change. Missing values are shown as unavailable rather than always as zero; a prior period with no baseline may not have a meaningful percentage comparison. ## Improve the underlying records Analytics relies on recorded work and lifecycle events. Keep experiment dates and states accurate, and connect ideas to the experiments that follow them. If totals seem unexpected, compare the relevant lists and dates before concluding that activity has been lost. For conversion analysis of a particular test, open its [Results](https://conversionlab.app/docs/experiments/results) page. For upcoming work, use the [Roadmap](https://conversionlab.app/docs/experiments/roadmap). --- Source: https://conversionlab.app/docs/experiments # Experiments and results Plan experiments, map the data, and review the outcome in context. ## Choose a task [Plan and document an experiment](https://conversionlab.app/docs/experiments/plan) Record a hypothesis, dates, metrics, research, and the next decision. [Manage variations and traffic allocation](https://conversionlab.app/docs/experiments/variations) Set a control, describe alternatives, and maintain the planned allocation. [Read experiment results](https://conversionlab.app/docs/experiments/results) Interpret descriptive totals, analysis status, variant effects, and traffic checks. [Plan work on the roadmap](https://conversionlab.app/docs/experiments/roadmap) Review experiment timing and add context that affects interpretation. [Review experimentation activity in Analytics](https://conversionlab.app/docs/experiments/analytics) Use signals, execution balance, and detailed operational metrics. --- Source: https://conversionlab.app/docs/experiments/plan # Plan and document an experiment Record a hypothesis, dates, metrics, research, and the next decision. An experiment brings the proposed change and its measurement plan together. Owners, admins, and users can create and edit experiments in a project, subject to the team's plan and record limits. ![Experiments in the fictional Acorn Store project, showing their names and planning fields.](https://conversionlab.app/docs/images/workflows/experiments.webp) ## Create the plan 1. Open **Experiments** and choose the create-experiment action. 2. Enter a name and description, select a state, and link the pages involved. 3. Save, then open the detail page. 4. Write the **Hypothesis**: the proposed change, the audience or situation, and the effect you expect. 5. Set the experiment's dates and measurement fields, including its primary metric. 6. Add [variations and traffic allocation](https://conversionlab.app/docs/experiments/variations). 7. Link **Connected Research** and **Connected Ideas**, then attach relevant design or implementation material. The description explains the test. The hypothesis explains what it is intended to establish. Keeping the original intent clear helps interpret a result later. ## Coordinate review Use Comments for discussion when the plan includes collaboration. The **Client approval** section shows the latest recorded approval and offers **Record approval** to team members, including viewers. Approval records identify the user and time; they document a review event rather than launching the experiment. ## Run and conclude the test Run the actual website test through your testing platform. [Map the experiment and sync its data](https://conversionlab.app/docs/integrations/testing-platforms) to make supported reporting available. Update the result status, result, decision, and stop reason when relevant. Available decisions include Implement, Rollout, Retest, Iterate, and Reject. These fields let you distinguish the observed outcome from what your team chooses to do next. Use [Results](https://conversionlab.app/docs/experiments/results) to review analysis, and capture a [learning](https://conversionlab.app/docs/research/learnings) with the conditions under which the finding applies. --- Source: https://conversionlab.app/docs/experiments/results # Read experiment results Interpret descriptive totals, analysis status, variant effects, and traffic checks. Open an experiment's **Results** page after mapping and syncing it with a supported testing provider. Results show the baseline, last sync time, visitor and conversion totals, overall conversion rate, Sample Ratio Mismatch, and variant effects. ![A synthetic experiment report comparing a 5% baseline conversion rate with a 6% variation conversion rate, with traffic checks and variant effects.](https://conversionlab.app/docs/images/workflows/experiment-results.webp) ## Check readiness before the conclusion 1. Verify the correct experiment, baseline, and primary metric. 2. Check the last sync time and any status banner. 3. Review visitor and conversion totals for the expected variations. 4. Inspect **Sample Ratio Mismatch** before using statistical conclusions. 5. Read the effect estimate, uncertainty, and corrected significance together. The current statistical report uses fixed-horizon, two-sided analysis with Holm correction for the reported comparisons. It supports rate-per-user primary metrics. The planned end date must have passed and the result status must be stopped before inference is ready. Interim totals can still be descriptive. ## Understand report states | Status message | What to do | | ----------------------------------------------- | -------------------------------------------------------------------------- | | No synced result data | Map and sync the experiment. | | Result mapping is incomplete | Map the primary metric and every provider variation one-to-one. | | Primary metric is not supported yet | Check the metric type; fixed-horizon v1 supports rate-per-user metrics. | | Fixed-horizon analysis is not ready | Check the planned end date and stopped result status. | | Not enough data for a trustworthy conclusion | Keep the result descriptive until the analysis checks pass. | | Traffic allocation mismatch detected | Investigate expected versus observed allocation before using significance. | | Result data is stale | Sync again and inspect the refreshed status. | | Experiment configuration cannot be analyzed | Check baseline, allocation, source, and observed counts. | | Statistical analysis is temporarily unavailable | Keep descriptive totals available and retry after recovery. | ## Interpret variant effects A label of **Significant after correction** means the comparison passed the report's corrected significance check. **Not significant after correction** does not establish that the variations are equivalent. When a readiness or traffic check blocks inference, use the status explanation instead of reading a displayed descriptive uplift as a decision. Record the team's decision separately on the experiment, and document the context in a [learning](https://conversionlab.app/docs/research/learnings). See [result troubleshooting](https://conversionlab.app/docs/troubleshooting/results) for a recovery checklist. --- Source: https://conversionlab.app/docs/experiments/roadmap # Plan work on the roadmap Review experiment timing and add context that affects interpretation. The **Roadmap** places project experiments on a timeline. Use it to understand when work is scheduled and where experiments overlap. ![The fictional Acorn Store experiment roadmap in June 2026, showing overlapping live experiments and a Summer promotion annotation.](https://conversionlab.app/docs/images/workflows/roadmap.webp) ## Review the schedule 1. Select the project and open **Roadmap**. 2. Use the timeline's date and display controls to inspect the relevant period. 3. Open an experiment card to inspect the experiment and its dates. 4. Update experiment planning fields where needed, then return to the timeline to check the result. An experiment needs relevant dates to appear usefully on the timeline. A missing card may be outside the current date window or project rather than deleted. ## Add context with annotations Use the annotation action to add a named event or period such as a promotion, release, or operational change. Choose its type, start date, end date where applicable, and notes. Save and confirm it appears at the intended time. For example, an annotation named “Spring sale” can explain why several tests experienced unusual traffic during the same week. An annotation provides interpretation context; it does not change experiment measurements. Review or remove annotations when the underlying plan changes. Keep timing information factual so colleagues do not mistake a planned event for something that actually happened. For item status definitions see [states](https://conversionlab.app/docs/ideas/states); for program-level activity see [Analytics](https://conversionlab.app/docs/experiments/analytics). --- Source: https://conversionlab.app/docs/experiments/variations # Manage variations and traffic allocation Set a control, describe alternatives, and maintain the planned allocation. Variations represent the experiences compared by an experiment. The control is the baseline used to interpret the alternatives. ## Add and describe variations 1. Open the experiment detail page and locate **Variations**. 2. Use the add action, enter a variation name, and save. 3. Review the control and alternatives so each name matches the intended experience. 4. Adjust the traffic allocation from the variation list. A newly added variation starts at **0% traffic**. Adding it does not automatically change your testing platform or include it in a running test. ## Distribute traffic Use the allocation controls to set percentages. Lock a variation's allocation when you want it held while distributing the remainder. **Distribute equally** distributes the available traffic across eligible unlocked variations. Confirm the planned allocation is valid for the full experiment and agrees with the provider configuration. The expected allocation is used for [Sample Ratio Mismatch checks](https://conversionlab.app/docs/experiments/results); it should describe the actual design rather than being changed to fit observed traffic after the test. ## Map provider variations A linked indicator shows a variation connected to a provider. Use **Map** for an unmapped variation and select the corresponding provider variation. Use the unmap action when a link is wrong, then select the correct replacement. Supported analysis requires every provider variation to be mapped one-to-one, with a valid baseline and primary metric. Similar names alone do not confirm a correct mapping. Deletion removes a variation and may leave a report without a required mapping or baseline. Review the experiment and result status after changing its variation set. --- Source: https://conversionlab.app/docs/getting-started/account-access # Create an account or join a team Register, accept an invitation, verify your email, and recover access. Choose **Open app** at the top of the documentation sidebar to continue to your workspace. If you are signed out, sign in first. New users can choose **Start free trial** in the sidebar to begin a Team trial; this promotion is hidden for signed-in users. ## Create an account 1. Open **Create an account** from the sign-in page. 2. Enter your name, email, password, and password confirmation. 3. Complete email verification if prompted. You can resend the verification email from the verification screen. 4. Follow **User Welcome** for a short introduction, then create your workspace. User Welcome introduces ConversionLab to you personally. [Team Setup](https://conversionlab.app/docs/getting-started/team-setup) configures a particular team and is a separate step. Creating a normal workspace starts on the Free plan; a paid trial is a distinct signup choice when offered. ## Join an invited team Open the invitation link using the email address that received it. Sign in if you already have an account, or register from the invitation flow. Once accepted, the team becomes available in the team switcher. If the link is missing a token, expired, or no longer valid, ask an owner or admin of that team to issue a new invitation. An invitation does not grant access to other teams owned by the same organization or agency. ## Sign in and reset your password Sign in with your email and password. Use **Forgot Password** if you cannot sign in, then follow the reset email and enter the new password twice. While signed in, change your password in **Settings → Account → Password** using your current password. If you reach **Create your workspace**, your account has no team to open yet. Create the intended team or follow your invitation before creating a duplicate. If you have several teams, use the team switcher to enter the one containing your work. See [access and saving problems](https://conversionlab.app/docs/troubleshooting/access-and-saving) for permission and session errors. --- Source: https://conversionlab.app/docs/getting-started/finding-your-work # Find and organize your work Navigate teams, projects, lists, filters, detail pages, and bulk actions. ## Choose the workspace first Use the team switcher at the top of the sidebar to change teams. Teams hold separate work; the team name matters when a familiar project or item is missing. Select a project from the sidebar before opening Research, Ideas, Experiments, Surveys, or project settings. Project-specific settings follow that selection. Agency accounts may first show **Clients**; open a client workspace before working on its projects. ## Use lists and detail pages Open a work area from the sidebar, narrow its table using the filters it offers, and select a row to open the item. Sorting and visible columns help you compare work without opening every detail page. Filter choices vary by area: observations have review and source filters, while experiments and ideas use their own states and definitions. Use **Display** on tables that offer it to show or hide columns. Use **Reset** to clear active table filters. If the list is empty, its add action can open the relevant create form directly. A detail page contains the item's description, relationships, and editable fields. Use the breadcrumb to return to a parent list. Links to connected work keep the surrounding research and experiment context available. ## Act on several items Where a list offers row selection, select the intended records and choose an available bulk action. Check the current filters and selection before moving, linking, changing state, archiving, or deleting records. Only actions supported by that work area appear. An archived item and a deleted item are not always equivalent. Observations have an explicit archive and restore flow; other deletion dialogs may describe permanent removal. Read the specific confirmation before continuing. ## Navigate with the keyboard Press `?` outside an editable field to open the shortcut list. Navigation shortcuts are sequences: press `G`, then the second key within a second. | Shortcut | Destination | | ------------ | ----------------- | | `G` then `D` | Dashboard | | `G` then `P` | Profile settings | | `G` then `R` | Research insights | | `G` then `I` | Ideas | | `G` then `E` | Experiments | | `G` then `T` | Roadmap | | `G` then `S` | Settings | The shortcuts are ignored while typing in an input, text area, or editor. They do not bypass the selected team's access rules. ## Recover an apparently empty list Clear search and filters, verify the project and team, and check the relevant review or archive tab. If you still cannot see the item, ask a teammate to verify its location and your membership. See [missing data](https://conversionlab.app/docs/troubleshooting/missing-data). --- Source: https://conversionlab.app/docs/getting-started # Getting started Set up your account and team, then connect your first workflow. ## Choose a task [Connect your first research-to-experiment workflow](https://conversionlab.app/docs/getting-started/quick-start) Follow one small example from evidence to a documented experiment. [Create an account or join a team](https://conversionlab.app/docs/getting-started/account-access) Register, accept an invitation, verify your email, and recover access. [Complete Team Setup](https://conversionlab.app/docs/getting-started/team-setup) Prepare the project, AI choice, pages, audiences, and metrics for your team. [Find and organize your work](https://conversionlab.app/docs/getting-started/finding-your-work) Navigate teams, projects, lists, filters, detail pages, and bulk actions. --- Source: https://conversionlab.app/docs/getting-started/quick-start # Connect your first research-to-experiment workflow Follow one small example from evidence to a documented experiment. Use this walkthrough after [Team Setup](https://conversionlab.app/docs/getting-started/team-setup). You need an owner, admin, or user role to create the work items. Choose the intended team and project before starting. ![A new idea for the fictional Acorn Store project, with its proposed change filled in before creation.](https://conversionlab.app/docs/images/workflows/create-idea.webp) ## 1. Record what you observed Open **Research → Observations** and create an observation such as “Visitors ask whether delivery is included.” Add the source label, what happened, and when it was observed. Keep the statement close to the evidence rather than presenting a proposed solution as a fact. ## 2. Explain why it matters Open **Research → Insights** and create “Unclear delivery costs make the total price hard to assess.” Link the supporting observation and the relevant page. The insight gives your interpretation a traceable source. ## 3. Propose a change Open **Ideas**, create “Show delivery information next to the price,” and add a description. On the idea detail page, link the insight and the relevant pages and metrics. Score it with a [priority model](https://conversionlab.app/docs/ideas/prioritize) if your project uses one. ## 4. Plan the test Open **Experiments**, create an experiment, and connect the idea and research. Write a hypothesis that names the proposed change and intended effect. Add the control and test variations, choose the primary metric, and set the planned dates. Recording an experiment in ConversionLab does not by itself launch a test on your website. Use your testing platform to run the experiment, then [map and sync its data](https://conversionlab.app/docs/integrations/testing-platforms). ## 5. Bring the outcome back into your knowledge Review [experiment results](https://conversionlab.app/docs/experiments/results) after the required data and analysis conditions are satisfied. Record the result, next decision, and a [learning](https://conversionlab.app/docs/research/learnings) linked to the research. The next idea can then build on a documented outcome. You now have a connected chain of source evidence, interpretation, proposed action, and experimental follow-through. Use the links between items to explain a decision to another teammate. --- Source: https://conversionlab.app/docs/getting-started/team-setup # Complete Team Setup Prepare the project, AI choice, pages, audiences, and metrics for your team. Owners and admins complete Team Setup for the team. A newly created team already has a **Default Project**; use the setup checklist to confirm or rename it. ## Work through the checklist 1. **Project:** confirm the Default Project or give it the name your team uses. 2. **AI choice:** acknowledge whether your team wants AI-assisted experiences. Owners and admins can change Team AI Opt-Out later in [AI Settings](https://conversionlab.app/docs/ai/privacy). 3. **Pages and audiences:** add the key website areas and visitor groups you work with. You can enter them manually, use [Airtable Import](https://conversionlab.app/docs/integrations/airtable-import), or use a supported [Integration Sync](https://conversionlab.app/docs/integrations/testing-platforms). 4. **Metrics:** define the outcomes you measure or import supported metrics from a connected provider. 5. Use **Skip For Now** explicitly for pages and audiences or metrics if you need to return to them later. 6. Review the checklist and use the finish action to make the team **Setup Complete**. The project and AI choice need an explicit acknowledgment. Pages and audiences, and metrics, must be completed or explicitly skipped. Connecting vendor integrations, inviting teammates, and watching learning resources are recommended steps; they do not block finishing setup. ## What changes after setup Setup progress is saved per team. Once you finish, the setup checklist stops being the team's primary dashboard experience. Switching to a different team can show that team's unfinished setup. Skipping a definition does not create it. Before linking a metric, page, or audience to later work, add it in [project settings](https://conversionlab.app/docs/concepts/definitions). An optional import is a way to complete a concept step, not a requirement for using ConversionLab. If setup remains visible, check the required steps and use the deliberate finish action. Closing the checklist or completing User Welcome does not mark Team Setup complete. --- Source: https://conversionlab.app/docs/ideas # Ideas and prioritization Build a useful backlog and decide which ideas deserve attention. ## Choose a task [Capture ideas and connect the evidence](https://conversionlab.app/docs/ideas/manage-ideas) Build an idea backlog with research, pages, metrics, and experiment links. [Score ideas with a priority model](https://conversionlab.app/docs/ideas/prioritize) Choose a project model, define inputs, and compare idea scores consistently. [Customize idea and experiment states](https://conversionlab.app/docs/ideas/states) Describe your workflow with named states and experiment categories. --- Source: https://conversionlab.app/docs/ideas/manage-ideas # Capture ideas and connect the evidence Build an idea backlog with research, pages, metrics, and experiment links. An idea proposes a change your team might make. Open **Ideas** in the selected project. Owners, admins, and users can create and maintain ideas; the Free plan has a record allowance. ![Ideas for the fictional Acorn Store project, with states and priority information in the list.](https://conversionlab.app/docs/images/workflows/ideas.webp) ## Create an idea 1. Open the create-idea action and name the proposed change. 2. Describe what you want to change and why it may help. 3. Choose an idea state and link relevant pages and metrics. 4. Choose **Create idea**. Open the saved idea to update its detail fields, attach supporting material, and connect the research behind it. An idea with a linked insight is easier to assess than a proposal with no visible evidence. ## Prepare it for prioritization Make the intended benefit and effort understandable before scoring it. Use the project's [priority model](https://conversionlab.app/docs/ideas/prioritize) consistently across ideas. Use states, tags, and list filters to keep the backlog usable rather than encoding the workflow only in the title. ## Connect it to an experiment Link the idea from an experiment's **Connected Ideas** section, or use the connection actions on the idea detail page. An experiment can preserve the idea's rationale while adding a specific hypothesis, variations, and planned measurements. Changing an idea's state is separate from launching an experiment. ConversionLab records the work and its relationships; the testing platform runs the website test. Use the list's available selection actions for bulk updates. Before deleting an idea, review its connected research and experiments and the deletion confirmation. See [planning an experiment](https://conversionlab.app/docs/experiments/plan) for the next step. --- Source: https://conversionlab.app/docs/ideas/prioritize # Score ideas with a priority model Choose a project model, define inputs, and compare idea scores consistently. A priority model combines structured inputs into an idea score. It helps compare ideas using agreed criteria; the score still depends on the values your team enters. ## Set up the model 1. Select the project and open **Settings → Project → Definitions → Priority**. 2. Choose an available model or create one with **Create Priority Model**. 3. Give it a name and description that explain when to use it. 4. Add inputs with stable keys, names, and types: number, boolean, or select. 5. Set relevant bounds, required fields, weights, and select option values. 6. Write the formula using the input keys, save, and make the intended model active for the project. For example, inputs named Impact, Confidence, and Effort could use the formula `(impact * confidence) / effort`. Give Effort a positive minimum so a zero denominator cannot produce an invalid score. The formula is an example, not a built-in recommendation for every team. ![An expanded ICE priority model showing its Impact times Confidence times Ease formula and the configurable inputs used to score ideas.](https://conversionlab.app/docs/images/workflows/priority-models.webp) ## Score an idea Open the idea's priority editor. Enter the project's configured values, review the calculated score, and save. Compare scores using the same model and assumptions. A missing score can mean required inputs are absent or the formula cannot produce a finite result. ## Change a model Explain changes to criteria before rescoring the backlog. Editing input keys, options, or the formula can alter existing score meaning. Use the available recalculation action after an intentional model change, then inspect a few representative ideas. The supported [API reference](https://conversionlab.app/docs/developer/api) includes model validation and recalculation for automated workflows. Deleting a priority model removes its priority scores from ideas; review the confirmation before deleting it. --- Source: https://conversionlab.app/docs/ideas/states # Customize idea and experiment states Describe your workflow with named states and experiment categories. States describe the progress of work. Idea states and experiment states are configured separately for the selected project under **Settings → Project → Definitions**. Lifecycle customization is included on Team, Agency Starter, Agency Pro, and Enterprise. Free, Solo, and Freelance use the available standard workflow without custom lifecycle configuration. ## Configure states 1. Open **Idea States** or **Experiment States**. 2. Choose **New state**, enter a recognizable name, and select its appearance. 3. For an experiment state, choose the category that matches its meaning. 4. Save and order the states to match the team's workflow. Experiment categories give the product a consistent way to understand progress even when you use custom state names. Renaming a state does not by itself redefine the category it belongs to. ## Apply the workflow Choose the appropriate state from an idea or experiment's detail fields, or use the list's supported bulk action. Keep state changes separate from the experiment's observed result status and final decision: progress, measurement, and business follow-through answer different questions. Before deleting a state, inspect the work that uses it and read the confirmation. If state editing is unavailable, check the team's plan and your permissions rather than creating duplicate states through another interface. --- Source: https://conversionlab.app/docs # Overview Practical guides for connecting research, ideas, experiments, and everything you learn along the way. ## Start here ![Preview of Your first workflow](https://conversionlab.app/docs/images/workflows/projects.webp) [Your first workflow](https://conversionlab.app/docs/getting-started/quick-start) Follow one example from a research observation to a documented experiment. ![Preview of Understand your results](https://conversionlab.app/docs/images/workflows/experiment-results.webp) [Understand your results](https://conversionlab.app/docs/experiments/results) Read variant effects, check traffic, and decide what the evidence supports. ![Preview of Build a feedback survey](https://conversionlab.app/docs/images/workflows/survey-builder.webp) [Build a feedback survey](https://conversionlab.app/docs/surveys/build) Turn a question into a survey and collect feedback from your visitors. ## Explore ConversionLab [Getting started](https://conversionlab.app/docs/getting-started) Set up your account, prepare your team, and find your way around. [Core concepts](https://conversionlab.app/docs/concepts) Understand how the work fits together, from projects to metrics. [Research](https://conversionlab.app/docs/research) Capture observations, develop insights, and preserve useful learning. [Ideas and prioritization](https://conversionlab.app/docs/ideas) Build an evidence-backed backlog and choose what to work on next. [Experiments and results](https://conversionlab.app/docs/experiments) Plan tests, manage variations, and review the outcome in context. [Surveys](https://conversionlab.app/docs/surveys) Create, publish, and review feedback surveys on your website. [Integrations and imports](https://conversionlab.app/docs/integrations) Connect your testing and research tools, or bring existing work with you. [Team administration](https://conversionlab.app/docs/team-administration) Manage people, roles, plans, credentials, and your team's vocabulary. [AI-assisted experiences](https://conversionlab.app/docs/ai) Work with the Agent, daily briefs, and audits, with your team in control. [Connect an external AI client](https://conversionlab.app/docs/developer/mcp-setup) Use MCP to give a compatible AI client scoped access to your ConversionLab work. ## Developers [Build with ConversionLab](https://conversionlab.app/docs/developer) Connect your own systems to project data and reporting with the REST API. [REST API reference](https://conversionlab.app/docs/developer/api) Find supported endpoints, request fields, response schemas, and examples. ## Help [Troubleshoot a problem](https://conversionlab.app/docs/troubleshooting) Work through access issues, missing data, surveys, and report warnings. [Use documentation in external AI tools](https://conversionlab.app/docs/developer/ai-readable-docs) Copy an article, read its Markdown, or use the public documentation in an AI tool. Examples and screenshots use fictional teams and data. Available features depend on your role, your team's plan, and optional experiences. See [roles and access](https://conversionlab.app/docs/team-administration/people-and-roles) if an action is missing. --- Source: https://conversionlab.app/docs/integrations/airtable-import # Import existing work from Airtable Authorize a base, review mappings, run an import, and inspect the results. Airtable Import is an optional **Source Import** path for an existing workspace. Owners and admins open it from **Settings → Organization → Imports**. CSV and Google Sheets are shown as future import options; use Airtable or manual setup for the currently implemented flow. ## Connect and choose a base 1. Open **Imports** and start an Airtable import. 2. In **Connect Airtable**, authorize access to the intended Airtable data. 3. In **Choose Base**, select the base and analyze its snapshot. 4. Continue to **Review Mapping** and select the target ConversionLab project. A base cannot be selected until authorization completes. If the base list is unexpected, review which account and base access you granted. ## Review the mapping before importing Generate a mapping suggestion when that action is available. Review **Tables**, field mappings, **Feedback**, and **Warnings**. Correct the suggested destination and fields rather than assuming a source table's name expresses the intended ConversionLab concept. For example, a table named “Roadmap” may contain ideas rather than experiments. Use the feedback field or mapping editor to state the correct interpretation. The **Plan JSON** tab exposes the saved import plan for closer review; ordinary imports can be configured through the table editor. Choose **Save mapping** or **Save and continue**. An import runs from the saved mapping plan, so unsaved edits are not the plan that will execute. ## Run and review 1. Open **Run Import** and start the background import. 2. Inspect progress rather than starting a duplicate import while one is running. 3. Open **Review Results** and compare imported, failed, skipped, and total records. 4. Read warnings and errors even if the import completed. 5. Open representative imported items in the target project and verify their fields and relationships. When a step is locked, finish its prerequisite or wait for the running import. Preserve the import record when seeking help so the team can identify the failed stage. Airtable Import brings source data into ConversionLab; it should not be treated as a promise of continuous two-way synchronization. --- Source: https://conversionlab.app/docs/integrations/clarity # Review behavioral signals from Microsoft Clarity Connect Clarity, sync behavioral evidence, and review suggested observations. The Microsoft Clarity integration imports behavioral analytics and can suggest observations for review. It needs a selected project and a Data Export API token generated by an administrator of the intended Clarity project. ## Connect and configure 1. Select the ConversionLab project and open **Settings → Project Integrations**. 2. Install **Microsoft Clarity** and enter the Data Export API token. 3. Choose whether automatic sync is active and select its frequency. 4. Set the lookback window and the signal thresholds, then save. The configuration includes minimum event count, relative lift, segment traffic, and repeat windows. These determine which signals qualify as suggestions. A completed sync can produce no new suggestions when the data does not meet those thresholds. ## Run and inspect a sync Use **Sync Now** when available. The integration card shows **Latest Integration Sync**, its status and time, and request usage or remaining quota when available. A disabled sync button explains whether a sync is running or a quota or scheduling restriction applies. Wait for the active sync to finish before requesting another. Check the displayed restriction rather than repeatedly retrying a quota-limited request. ## Review the evidence Open **Research → Observations → Suggested**, filter to the source if helpful, and inspect each signal's evidence. Accept useful observations, dismiss unsuitable ones, and link them to the relevant pages or insights. Dismissal retains the suppression record. Permanently deleting a dismissed or archived observation removes that record, so the same Clarity signal can be generated again during a future sync. If nothing appears, check the chosen project, latest sync result, lookback window, thresholds, and review tabs. See [observations](https://conversionlab.app/docs/research/observations) for the full review lifecycle. --- Source: https://conversionlab.app/docs/integrations # Integrations and imports Connect vendor tools or bring existing source data into the right project. ## Choose a task [Connect a testing platform and map experiments](https://conversionlab.app/docs/integrations/testing-platforms) Bring provider data into ConversionLab with deliberate project and variation mapping. [Review behavioral signals from Microsoft Clarity](https://conversionlab.app/docs/integrations/clarity) Connect Clarity, sync behavioral evidence, and review suggested observations. [Send project activity alerts to Slack](https://conversionlab.app/docs/integrations/slack) Connect a Slack channel and choose which project activities generate alerts. [Import existing work from Airtable](https://conversionlab.app/docs/integrations/airtable-import) Authorize a base, review mappings, run an import, and inspect the results. --- Source: https://conversionlab.app/docs/integrations/slack # Send project activity alerts to Slack Connect a Slack channel and choose which project activities generate alerts. Slack notifications send selected project activity to a shared channel. They are configured separately from your personal in-app notification preferences. ## Connect Slack 1. Select the project and open **Settings → Project Integrations**. 2. Install **Slack** and enter the incoming webhook URL for the intended channel. 3. Set a channel override if your webhook setup supports and requires one, then save. 4. Open **Notifications** on the integration card or **Slack Notifications** in project settings. Treat the webhook URL as a credential. Keep it in integration configuration rather than pasting it into shared comments or documentation. ## Choose activity alerts In **Project Slack Notifications**, review the integration state and switch on the activity alerts your team needs. Save the configuration when the screen requests it. Test using a relevant project action, then check the intended Slack channel. The settings navigation shows Slack Notifications when the integration is active. If it is missing, confirm the selected project and active Slack connection first. ## Recover missing delivery Check that the activity type is enabled and that the webhook is still valid for the channel. If the channel or permissions changed, update the connection in **Configure**. Use [personal notification settings](https://conversionlab.app/docs/team-administration/profile-notifications) for in-app alerts; those preferences do not configure the project's Slack channel. --- Source: https://conversionlab.app/docs/integrations/testing-platforms # Connect a testing platform and map experiments Bring provider data into ConversionLab with deliberate project and variation mapping. Vendor integrations connect an external tool to your ConversionLab work. The shipped testing provider definitions include **ABlyft** and **Kameleoon**. Use the providers offered in your project's Integrations screen; a provider name mentioned elsewhere does not imply an installed connection. ## Connect the provider 1. Select the intended project and open **Settings → Project Integrations**. 2. Choose the provider's install action. 3. Enter the requested credentials and source identifiers. 4. Review the sync frequency and automatic experiment matching settings, then save. ABlyft asks for an API token and project ID. Kameleoon asks for an API client ID, API client secret, and site code. Use credentials authorized for the external project you intend to connect. ![Project integrations for the fictional Acorn Store, with an active ABlyft connection and available Kameleoon, Microsoft Clarity, and Slack integrations.](https://conversionlab.app/docs/images/workflows/integrations.webp) ## Import definitions and map work Use the import actions in **Metrics**, **Pages**, and **Audiences** for provider data that is available for discovery. Review each proposed match to an existing definition or create the intended new definition. Map a ConversionLab experiment to its external experiment, then map each variation to the corresponding provider variation. Automatic name matching can assist with matching, but inspect the result when names are similar or experiments have been duplicated. The primary metric and every provider variation must have a correct one-to-one mapping for supported [result analysis](https://conversionlab.app/docs/experiments/results). The control and expected allocation must also describe the actual test. ## Keep the connection healthy Check the integration's state and available sync information. Use **Configure** to update credentials or supported schedule settings. If data is missing, inspect mappings and freshness before reconnecting the provider. **Disconnect** removes configuration and mappings. It is more disruptive than waiting for a running sync or correcting a single mapping. Review the confirmation and preserve the configuration you need before disconnecting. Integration allowances depend on the plan. The Free plan currently includes one tool integration; [Billing](https://conversionlab.app/docs/team-administration/billing) shows the account's current availability. --- Source: https://conversionlab.app/docs/research/evidence # Understand research collections and screen evidence Keep source context with observations, screen annotations, and collections. Research can contain more than a written note. ConversionLab supports research collections, screens, and screen annotations as structured evidence, including records created by supported API workflows. ## Read an observation’s evidence Open an observation and inspect **Evidence** for its source details. If it has **Screen Annotations**, those links identify the screen evidence attached to the observation. An annotation supplies context for a region or finding; the observation explains what was noticed there. The observation's source label, evidence kind, confidence, and observed date help distinguish first-hand notes from imported or generated material. Review that information before accepting a suggestion or using it to support an insight. ## Use collections and screens through an integration The supported REST API exposes research collections, screens, and screen annotations. Use the [API reference](https://conversionlab.app/docs/developer/api) for their request fields, related IDs, and response definitions. These objects can support observation and audit workflows even though the main product navigation centers on Observations, Insights, and Learnings. Keep records and their relationships in the intended project. When importing evidence, include enough descriptive text that a teammate can understand its significance without relying solely on a screenshot. For ordinary file uploads on ideas, insights, or experiments, use [attachments](https://conversionlab.app/docs/concepts/collaboration). For AI-assisted page captures and findings, see [audits](https://conversionlab.app/docs/ai/audits). --- Source: https://conversionlab.app/docs/research # Research Capture observations, explain insights, and preserve what your team has learned. ## Choose a task [Capture and review observations](https://conversionlab.app/docs/research/observations) Record source evidence and review suggested observations before using them. [Turn observations into insights](https://conversionlab.app/docs/research/insights) Explain a research finding and connect it to evidence and future work. [Preserve what the team has learned](https://conversionlab.app/docs/research/learnings) Write reusable conclusions with confidence, timing, and supporting insights. [Understand research collections and screen evidence](https://conversionlab.app/docs/research/evidence) Keep source context with observations, screen annotations, and collections. --- Source: https://conversionlab.app/docs/research/insights # Turn observations into insights Explain a research finding and connect it to evidence and future work. An insight states what the evidence suggests about your visitors or their experience. Use **Research → Insights** in the selected project to capture that interpretation. ![The fictional Acorn Store insight list, showing research findings organized for review.](https://conversionlab.app/docs/images/workflows/insights.webp) ## Create an insight 1. Choose the create-insight action and give the insight a clear title. 2. Explain the finding, who it affects, and the evidence supporting it in the description. 3. Link the relevant pages and supporting observations. 4. Choose an insight label when your project uses labels, then save. The optional **Legacy source** field retains a source label. For a traceable research chain, use supporting observations to carry the actual evidence and its origin. ## Connect the finding On the detail page, use **Supporting Observations** to add or remove evidence links. Use **Connected Ideas** and **Connected Experiments** to link work influenced by the insight. The **Learnings** section connects later conclusions back to the research. Attach a supporting file in **Attachments** if useful. Keep the description understandable without that file, so teammates can assess the claim directly. **Comments** and **Activity** provide discussion and history when the team's plan supports comments. ## Revisit the interpretation An insight can change as new evidence arrives. Update the description to explain what is now understood, preserve the links that support it, and connect any follow-up learning. Removing a relationship does not mean the evidence itself has been disproven. If a related item is unavailable in the link picker, confirm it belongs to the same project. Cross-project relation validation prevents accidentally linking unrelated project data. See [observations](https://conversionlab.app/docs/research/observations), [ideas](https://conversionlab.app/docs/ideas/manage-ideas), and [collaboration](https://conversionlab.app/docs/concepts/collaboration). --- Source: https://conversionlab.app/docs/research/learnings # Preserve what the team has learned Write reusable conclusions with confidence, timing, and supporting insights. A learning captures what the team now understands. It can summarize a supported conclusion, a limitation, or a finding worth remembering before another experiment. ## Create a learning 1. Open **Research → Learnings** in the intended project. 2. Create a learning with a short title describing the conclusion. 3. Explain the context and limits in the description: the audience, page, evidence, and circumstances that matter. 4. Set the confidence and **Learned at** date when known. 5. Link the insights that support it and choose **Create learning**. On the detail page, **Learning Context** shows the confidence and date. Use **Linked Insights** to follow the supporting research or adjust those relationships. ## Keep it reusable “Delivery copy always increases conversion” overstates a single result. “Delivery copy helped first-time buyers in the tested checkout flow” preserves the conditions under which the finding was supported. Include uncertainty when evidence is limited or results were inconclusive. A learning does not replace the underlying [experiment result](https://conversionlab.app/docs/experiments/results). Keep the result and its configuration available through the connected research, so the next team member can understand how the conclusion was reached. Owners, admins, and users can maintain learnings. If editing fails, check your role and [billing mode](https://conversionlab.app/docs/team-administration/billing). --- Source: https://conversionlab.app/docs/research/observations # Capture and review observations Record source evidence and review suggested observations before using them. An observation records something seen or reported in a source. Open **Research → Observations** in the intended project. Owners, admins, and users can create and edit observations; viewers can inspect the work. ![The observations list for fictional Acorn Store research, with review tabs and source evidence.](https://conversionlab.app/docs/images/workflows/observations.webp) ## Create an observation 1. Open the create-observation action and write a concise name describing what happened. 2. Add the source-bound detail in the description. 3. Set the source, source label, evidence kind, confidence, and observed date when known. 4. Link existing insights if they already explain this evidence, then choose **Create observation**. 5. Open the saved observation to link relevant pages or supporting insights and review its evidence. Source labels make records easier to recognize: “Pricing interviews, June” is more useful than “Research.” An observation can carry structured evidence from an integration or screen annotation as well as a written description. ## Review suggestions The list separates **Active**, **Suggested**, **Dismissed**, and **Archived** observations. Integration suggestions appear under Suggested until reviewed. Open a suggestion and inspect the underlying evidence, source, date, and confidence. **Accept** it when it is useful evidence for your team. **Dismiss** it when it should not be used. Accepted observations appear in Active. Source filters and bulk actions help work through several suggestions, but review the selected evidence before accepting it. When AI is available, the draft-insight action can propose an interpretation from eligible observations. Review the wording and supporting links before saving the resulting insight. You can always [create an insight manually](https://conversionlab.app/docs/research/insights). ## Archive, restore, and remove Archive observations you want to retain outside active work. Restore eligible observations from Dismissed or Archived when you need them again. Dismissed and archived observations cannot be linked or used to draft an insight until restored. Permanent deletion removes the record and its suppression information. For Clarity suggestions, that means the same signal may be generated again in a future sync. Use dismissal when your goal is to stop reviewing a rejected signal, rather than deleting its suppression history. --- Source: https://conversionlab.app/docs/surveys/build # Build a feedback survey Create questions, organize the visitor experience, and save your survey. Surveys collect feedback from website visitors. Owners, admins, and users can create and edit them within a project. ![The Build tab for a fictional Checkout Experience Survey, showing saved questions and the survey preview.](https://conversionlab.app/docs/images/workflows/survey-builder.webp) ## Create the survey 1. Select the project and open **Research → Surveys**. 2. Create a new survey, enter its name, and choose **Create Survey**. 3. Open the **Build** tab on the survey detail page. 4. Add the questions you need, edit their wording and settings, and arrange them in the intended order. 5. Review the preview, then choose **Save** for the builder changes. ## Choose the right question | Type | Visitor response | | --------------- | -------------------------- | | Single Choice | One option | | Multiple Choice | More than one option | | Rating | A 1–5 star rating | | NPS | A score from 0 to 10 | | Short Text | A short single-line answer | | Long Text | A paragraph | | Yes / No | One of two answers | | Emoji Reaction | An emoji rating | Use a **Welcome Screen** to introduce the survey and a **Thank You Screen** for the closing message. These screens provide context rather than collected answers. Review required questions and choice labels before publishing. ## Save and preview deliberately Builder changes and survey settings have separate save actions. Use **Discard Changes** only when you want to return to the saved version. Check both desktop and narrower layouts in your website review, especially for long choice labels. A saved survey is not necessarily live. Use [publishing and targeting](https://conversionlab.app/docs/surveys/publish) to configure the widget, install the project snippet, and set the survey to Active. To reuse an existing structure, use the survey's duplicate action and review the copied name, questions, settings, and status before making the new survey active. --- Source: https://conversionlab.app/docs/surveys # Surveys Build feedback surveys, publish them on your website, and review the answers. ## Choose a task [Build a feedback survey](https://conversionlab.app/docs/surveys/build) Create questions, organize the visitor experience, and save your survey. [Publish and target a survey](https://conversionlab.app/docs/surveys/publish) Install the project widget and control when, where, and how a survey appears. [Review, export, and reset survey answers](https://conversionlab.app/docs/surveys/responses) Read summaries and individual responses, export the selected status, and manage test data. --- Source: https://conversionlab.app/docs/surveys/publish # Publish and target a survey Install the project widget and control when, where, and how a survey appears. Before publishing, [build and save your questions](https://conversionlab.app/docs/surveys/build). You also need permission to add a script to the website where you want to collect feedback. ## Configure when it appears Open the survey's **Settings** tab and choose a trigger: button, delay, scroll, exit intent, or automatic opening. Configure the delay or scroll amount where relevant. For triggers other than a button, **Show trigger button** lets visitors reopen the widget after closing it. Choose the display frequency: every page visit, once per visitor, once per session, once per day, or once per week. Set **Priority** if more than one survey can match a page; higher priority wins. ## Target the right URLs Enable **URL targeting** and add **Show on URLs** and **Hide on URLs** rules. Wildcards such as `/pricing*` or `/blog/*` let a rule cover a group of paths. Review both inclusion and exclusion rules on representative URLs before launch. A widget can be installed correctly and still not appear because the current URL, trigger, frequency, or competing survey makes it ineligible. ## Match the website Configure colors, position, stacking order, theme, trigger text, title visibility, and progress indicator. **Personal Touch** can show a sender name, role, and avatar. The language setting localizes widget interface text; write your question content in the language you want visitors to read. Choose **Save Settings** after editing. Build changes and settings changes are saved separately. ## Install and activate 1. Open **Embed** and copy the generated project snippet. 2. Add it to your website once, before the closing body tag. 3. Set the survey status to **Active**. 4. Visit an eligible page and complete a test response. 5. Confirm it appears in the survey's **Answers** tab. The snippet loads every active survey in that project. Do not add a separate copy for each survey. **Draft**, **Paused**, and **Archived** surveys do not collect through the active widget flow. Use Paused when you need to stop a survey while retaining its configuration and answers. See [widget troubleshooting](https://conversionlab.app/docs/troubleshooting/survey-widget) if the survey does not appear. --- Source: https://conversionlab.app/docs/surveys/responses # Review, export, and reset survey answers Read summaries and individual responses, export the selected status, and manage test data. Open a survey to review its collected feedback. **Overview** summarizes the responses; **Answers** shows individual submissions and partial responses. ![Surveys in the fictional Acorn Store project, including their collection status and response information.](https://conversionlab.app/docs/images/workflows/surveys.webp) ## Read the overview Review the response counts and question-level summaries. Different question types have different summaries, including choice distributions, ratings, NPS, and text answers. Read the underlying answers before treating a summary as a complete explanation of visitor behavior. When AI is available, a survey's AI action can open a conversation about its responses. Check any interpretation against the actual answers and preserve useful evidence as research. ## Inspect individual answers Open **Answers** and filter by **All**, **Submitted**, or **Partial**. A partial response is an unfinished response; it is not equivalent to a completed survey. Inspect the shown timestamps and available visitor context alongside the answers. Use **Load more** when more responses are available. A list can have more collected answers than the currently loaded rows. ## Export Choose **Export**, then **CSV** or **Excel (.xlsx)**. The selected response-status filter determines whether the export includes all, submitted, or partial responses. Confirm that scope in the export menu before downloading. ## Reset test answers or delete a survey Use **Reset answers** only when you intend to remove every collected answer and response summary from that survey. The survey remains available and can collect new answers, but the deleted answers cannot be recovered through this action. Deleting the survey removes the survey and its collected answers. Pause the survey instead when your goal is to stop collecting while keeping the research. If an expected answer is missing, clear the status filter, check the project and survey, and verify that the visitor completed the expected survey rather than another active survey. --- Source: https://conversionlab.app/docs/team-administration/agency-clients # Manage an agency and client workspaces Keep client work isolated while reviewing delivery across your agency. An agency account groups client workspaces under a billing account. Each client workspace is a separate team with its own project work and membership. ## Open client work Use **Clients** to review client workspace setup, experiment progress, and recorded approvals. Open a client's name to enter that workspace, then select its project to work on research, ideas, experiments, and surveys. The agency shell focuses on Clients and Settings. If project navigation is absent there, open the intended client workspace rather than creating project work in the shell. ## Create a client workspace Agency owners and admins can choose **Add client** in the team switcher. The account's plan governs how many client workspaces and seats are included. Confirm the agency billing context and client name before creating the workspace, then complete that client's [Team Setup](https://conversionlab.app/docs/getting-started/team-setup). ## Assign staff and client access Owners and admins manage the client's **Users** settings. Use **Agency Staff Access** to add eligible agency staff, or invite the client's own members with appropriate access. A staff member needs access to the particular client workspace; agency membership should not be confused with unrestricted access to every client record. Client approval events on experiments appear in the client overview. They identify recorded approvals and progress; open the underlying experiment for its complete plan and history. ## Convert an eligible organization An owner can inspect **Convert to agency account** in Organization settings. Conversion checks eligibility and shows blockers before allowing confirmation. It is a one-way conversion and requires entering the organization name. Do not delete existing work merely to clear a conversion blocker. Review the account structure and the stated eligibility requirements before choosing an agency setup. For account capacity and subscription options, see [Billing](https://conversionlab.app/docs/team-administration/billing). --- Source: https://conversionlab.app/docs/team-administration/api-keys # Create and revoke API keys Give scripts and external AI clients scoped access to one team. API keys are personal bearer tokens tied to the team selected when you create them. Create and revoke them while signed in through **Settings → Account → API Keys**. ## Create a key 1. Choose **Create key**. 2. Give it a name that identifies its purpose, such as “Reporting export.” 3. Select the intended team. 4. Choose **REST Read only**, **REST Read & Write**, **MCP Read only**, or **MCP Read & Write**. 5. Set an optional expiration date and create the key. 6. Copy the token from **API key created** and store it in your integration's secret configuration. The plaintext token is shown only once. If you close the dialog without saving it, create a replacement and archive the unused key. MCP keys require a plan other than Free and an available MCP service. ## Understand permissions Token permissions limit what a client can request. Your current team role and the team's plan still decide whether the action is allowed. A write key cannot give a viewer ordinary work-item editing privileges. REST and MCP permissions are distinct. Use a REST key for HTTP API endpoints and an MCP key for the MCP connection. Switching teams in the browser or supplying another team ID does not change a token's team. ## Revoke a key Choose the archive action for the key and confirm **Archive API key**. Archiving keeps the record for audit purposes but immediately prevents authentication with that token. Applications using it lose access, so update them with a replacement first when rotating a working key. Use **Show archived** to review retained key records. See [REST authentication](https://conversionlab.app/docs/developer/authentication) and [MCP setup](https://conversionlab.app/docs/developer/mcp-setup) for connection examples. --- Source: https://conversionlab.app/docs/team-administration/billing # Manage plans, usage, and billing Understand plan limits, subscription changes, and read-only access. Owners and admins open **Settings → Organization → Billing** to review the current plan, usage, invoices, and available subscription actions. A client workspace can be covered by an agency billing account; check which account owns the subscription. ## Understand current availability Normal workspace creation starts on **Free**. The current Free allowance is one full user, one project, one tool integration, five experiments, twenty ideas, and twenty insights. Free AI usage has a monthly cap, and MCP is unavailable on Free. Solo and Freelance support individual workflows. Team, Agency Starter, Agency Pro, and Enterprise include comments and lifecycle customization. The Billing page and plan choices show the applicable seat, project, client workspace, and other allowances for your account. A plan's available features and a person's role are separate checks. Upgrading a plan does not turn a viewer into an editor. ## Change a subscription 1. Review the current plan and usage. 2. Choose an available plan change or checkout action. 3. Inspect the preview, included capacity, and any charge or adjustment shown. 4. Confirm only the intended plan and billing cycle. 5. Return to Billing and verify the resulting subscription state. Self-service plan changes are limited to supported plan pairs and keep the current billing cycle. Some agency conversions require an eligible empty organization. Enterprise, complimentary, and sales-assisted configurations may offer different controls; follow the action shown for that account. Use the billing portal for the payment and cancellation actions it offers. Subscription changes are made through the available in-product flow; not every plan can be changed directly from the portal. ## Read-only mode When billing places a team in blocked mode, existing work remains readable but changes are rejected. The app surfaces a read-only message; REST writes can return HTTP 402. Resolve the billing state before retrying an edit. If an active plan still rejects creation, inspect the specific allowance or validation message. Invitations, projects, and record limits are checked separately. --- Source: https://conversionlab.app/docs/team-administration # Team administration Manage people, projects, organization identity, plans, and credentials. ## Choose a task [Manage members, invitations, and roles](https://conversionlab.app/docs/team-administration/people-and-roles) Give each teammate the access they need in the intended workspace. [Update the organization name and logo](https://conversionlab.app/docs/team-administration/organization) Keep the team identity recognizable in the application. [Manage plans, usage, and billing](https://conversionlab.app/docs/team-administration/billing) Understand plan limits, subscription changes, and read-only access. [Manage an agency and client workspaces](https://conversionlab.app/docs/team-administration/agency-clients) Keep client work isolated while reviewing delivery across your agency. [Configure readable IDs with taxonomy](https://conversionlab.app/docs/team-administration/taxonomy) Set team numbering and optional project-specific sequences for work items. [Manage your profile and notifications](https://conversionlab.app/docs/team-administration/profile-notifications) Update personal details and decide which activity alerts you receive. [Create and revoke API keys](https://conversionlab.app/docs/team-administration/api-keys) Give scripts and external AI clients scoped access to one team. --- Source: https://conversionlab.app/docs/team-administration/organization # Update the organization name and logo Keep the team identity recognizable in the application. Owners and admins manage the selected team's identity in **Settings → Organization → General**. ## Update identity 1. Verify the selected team. 2. Edit **Organization name**. 3. Choose a logo image or remove the existing logo. 4. Save the changes and confirm the new identity appears. The logo upload accepts an image up to 2 MB. If it is rejected, use a smaller image file and retry. A blank organization name is not valid. The screen warns about unsaved changes when appropriate. Save or discard intentionally before moving away. Updating this name does not transfer data into another team. Agency conversion is a separate action with its own eligibility check and confirmation. See [agency and client workspaces](https://conversionlab.app/docs/team-administration/agency-clients) before using it. --- Source: https://conversionlab.app/docs/team-administration/people-and-roles # Manage members, invitations, and roles Give each teammate the access they need in the intended workspace. Owners and admins manage membership in **Settings → Organization → Users**. Access is team-specific: a role in one team does not automatically grant the same role elsewhere. ![Team Users for a fictional team, showing member access, pending invitations, and the Invite a Member form.](https://conversionlab.app/docs/images/workflows/team-settings.webp) ## Choose access | Role | Typical access | | ------ | ------------------------------------------------------------------------------------------------------------- | | Owner | Manages organization settings, people, billing, projects, and work. Some ownership actions are owner-only. | | Admin | Manages organization settings, people, billing, projects, and work within allowed administrative actions. | | User | Creates and edits project work such as research, ideas, experiments, and surveys. | | Viewer | Reads project work without ordinary work-item editing. Some collaborative actions have their own permissions. | Agency screens may use **Agency operator**, **Client editor**, and **Client viewer** to describe seat and access choices. Seat type affects billing and access classification; it is distinct from a REST or MCP token's abilities. ## Invite someone 1. Open **Users** and locate **Invite a Member**. 2. Enter the person's email and select their access. 3. Send the invitation. 4. Check **Pending Invitations** until it is accepted. Review the pending invitation controls if an email needs to be resent or an invitation withdrawn. The team's seat allowance includes relevant pending invitations, so an unaccepted invitation can affect capacity. ## Change or remove access Use the member's access selector to change their role where permitted. Review the affected workspace and any seat impact before saving. Use the remove action to end access to that team. If a change is rejected, read the validation message: an owner constraint, membership rule, or plan allowance may prevent the requested change. Do not assume an API key can override those restrictions. Client workspaces can also grant eligible agency staff access through **Agency Staff Access**. See [agency workspaces](https://conversionlab.app/docs/team-administration/agency-clients). For a failed invitation link, see [account access](https://conversionlab.app/docs/getting-started/account-access). --- Source: https://conversionlab.app/docs/team-administration/profile-notifications # Manage your profile and notifications Update personal details and decide which activity alerts you receive. Account settings follow the signed-in person. Project Slack notifications are a separate team configuration. ## Update your profile and password Open **Settings → Account → Profile** to change your name, email, or profile picture, then save. Open **Password** to enter your current password and the new password confirmation. If you cannot sign in, use [password recovery](https://conversionlab.app/docs/getting-started/account-access). ## Choose in-app alerts Open **Settings → Account → Notifications**. Review **Channels** and enable or disable in-app notifications. Under **Activity alerts**, choose the event types that should notify you. Open **Notifications** from the product sidebar to inspect delivered notifications and mark them read using the available controls. The sidebar indicator highlights unread activity. Follow a notification to the relevant work when you need its full context. A missing notification can mean the activity type or channel is disabled, or that the event did not apply to you. Check your settings and the underlying item before assuming the action failed. ## Change appearance Use the appearance control in the account menu to select the available light, dark, or system theme. Theme choice changes presentation; it does not affect saved work or another member's access. The same menu provides **Account**, **Send feedback**, and **Log out**. Use Log out to end the browser session; API keys remain independently managed under [API Keys](https://conversionlab.app/docs/team-administration/api-keys). For shared channel alerts, configure [Slack notifications](https://conversionlab.app/docs/integrations/slack) for the selected project. --- Source: https://conversionlab.app/docs/team-administration/taxonomy # Configure readable IDs with taxonomy Set team numbering and optional project-specific sequences for work items. Taxonomy assigns readable custom IDs to experiments, ideas, and insights. Team taxonomy supplies a default across projects; project taxonomy is an optional override. ## Configure team or project taxonomy 1. Open **Settings → Organization → Taxonomy** for the team's defaults, or **Settings → Project → Taxonomy** for the selected project. 2. Open the section for Experiments, Ideas, or Insights. 3. Edit the scheme's name, template, and next number, or create a project taxonomy where none exists. 4. Review **Preview** and save. Without a configured project section, new work uses the team taxonomy and global ID scope. Confirm the intended scope before creating a separate project sequence. ![Team taxonomy settings for experiments showing the readable-ID template, next sequence number, and generated EXP-0001 preview.](https://conversionlab.app/docs/images/workflows/taxonomy.webp) ## Build a template | Variable | Meaning | | ---------------- | ------------------------------------------------------- | | `{number}` | Next sequence number | | `{number:0000}` | Sequence number padded with zeroes | | `{year}` | Current four-digit year | | `{entity}` | EXP, IDEA, or INS | | `{project_code}` | Project code; frozen when a project sequence is created | For example, `{entity}-{number:0000}` produces IDs such as `EXP-0021`. Preview the actual output before saving, especially when combining team and project naming conventions. ## Assign IDs to existing records The backfill action assigns IDs to eligible existing work. Inspect the scheme and selected scope before running it. Changing a template governs the numbering configuration; do not assume it rewrites every already assigned ID. Custom IDs help people refer to work. They are separate from the numeric resource IDs used by the [REST API](https://conversionlab.app/docs/developer/api). --- Source: https://conversionlab.app/docs/troubleshooting/access-and-saving # Fix sign-in, permission, and saving problems Identify whether a failure comes from the session, team role, plan, or form fields. ## You cannot sign in Use **Forgot Password** from the sign-in screen, then follow the reset email. Complete email verification if prompted. An invitation must be accepted by the intended account; ask an owner or admin for a fresh invitation if the link is invalid. ## A team or action is missing Check the team switcher and selected project. Owners and admins manage organization settings and projects; users can edit ordinary project work; viewers have narrower access. An owner or admin can review your membership in **Settings → Users**. Plan availability is a separate check. For example, comments and lifecycle customization are not included on Free, Solo, or Freelance, and MCP is unavailable on Free. ## Changes fail to save 1. Keep the unsaved content available while reading the error. 2. Check the highlighted fields and required relationships. 3. Verify that selected pages, metrics, or other linked records belong to the correct project. 4. If the app reports read-only mode, ask the billing administrator to resolve the subscription state. 5. If your session has expired, sign in again and check the record before repeating the change. Survey **Build** and **Settings** have separate save actions. A preview change is not a saved change until the corresponding save completes. ## Uploads fail The browser attachment picker accepts images up to 5 MB; use JPEG, PNG, or GIF for formats accepted throughout the upload flow. Organization logos have a 2 MB image limit, and changing an existing project cover has a 1 MB server limit. The REST attachment API separately supports image and document formats up to 10 MB. Use the specific field's validation message when an upload is rejected. ## Ask for help with useful context Choose **Copy support context** below the article, then **Open feedback portal** and paste the article details into your request. Describe the action attempted, a redacted error message, and the approximate time. Keep the request suitable for a public feedback post: omit API tokens, integration credentials, private team records, and unredacted response data. --- Source: https://conversionlab.app/docs/troubleshooting # Troubleshooting Find the cause of access, data, survey, and reporting problems. ## Choose a task [Fix sign-in, permission, and saving problems](https://conversionlab.app/docs/troubleshooting/access-and-saving) Identify whether a failure comes from the session, team role, plan, or form fields. [Find missing work or integration data](https://conversionlab.app/docs/troubleshooting/missing-data) Check location, filters, review state, mappings, and sync status. [Fix a survey that does not appear](https://conversionlab.app/docs/troubleshooting/survey-widget) Check activation, installation, targeting, triggers, frequency, and competing surveys. [Resolve experiment report warnings](https://conversionlab.app/docs/troubleshooting/results) Restore reporting readiness without hiding data or allocation problems. --- Source: https://conversionlab.app/docs/troubleshooting/missing-data # Find missing work or integration data Check location, filters, review state, mappings, and sync status. ## A record is missing 1. Confirm the selected team and project. 2. Clear list search and filters. 3. For observations, inspect **Active**, **Suggested**, **Dismissed**, and **Archived**. 4. Follow a known item link or ask a teammate to confirm its location. 5. Check whether it was moved, archived, or deleted using the applicable work area's history and controls. Restore an observation from its available restore action when appropriate. A permanent delete cannot be undone through the ordinary restore flow. ## A selector has no matching records A relationship picker uses the selected project context. Define the missing page, audience, metric, state, or label in that project's settings. Do not create a similarly named duplicate before checking the existing definitions and filters. ## A provider is connected but results are absent Inspect the provider configuration, project/source identifiers, experiment mapping, variation mapping, primary metric, and last sync. A connection can exist without every necessary mapping being complete. For Clarity, inspect the latest sync status and configured thresholds, then check Suggested observations. A successful sync does not guarantee new suggestions. For Airtable, inspect the import's result counts and warnings, and verify the target project and saved mapping. An imported count does not mean every source field was mapped. See [testing integrations](https://conversionlab.app/docs/integrations/testing-platforms), [Airtable Import](https://conversionlab.app/docs/integrations/airtable-import), or [result troubleshooting](https://conversionlab.app/docs/troubleshooting/results) for the relevant recovery path. --- Source: https://conversionlab.app/docs/troubleshooting/results # Resolve experiment report warnings Restore reporting readiness without hiding data or allocation problems. Start with the status banner on the experiment's Results page. It identifies which condition blocks analysis. ## No data or incomplete mapping Confirm the provider connection, mapped external experiment, primary metric, and all variation mappings. Each provider variation needs a one-to-one match. Correct the mapping and sync before checking Results again. ## Unsupported or invalid configuration The current fixed-horizon report supports rate-per-user primary metrics. Check the metric type, baseline, expected traffic allocation, and observed counts. A descriptive total is not proof that the configuration is valid for inference. ## Fixed-horizon analysis is pending Confirm that the planned end date has passed and the result status is stopped. While the test is still running or before the planned horizon, totals remain descriptive. Do not mark a running experiment stopped simply to reveal a conclusion. ## Sample Ratio Mismatch Compare the intended provider allocation with the allocation recorded in ConversionLab, then investigate why observed traffic differs. Check mapping, targeting, tracking, and the provider's experiment setup. Significance remains gated while the mismatch is unresolved; changing expected percentages merely to match observed totals does not resolve the cause. ## Insufficient data, stale source, or unavailable engine Insufficient data means one or more analysis checks have not cleared. Stale source data needs another sync. Temporary engine unavailability can leave descriptive totals visible while analysis is unavailable; retry after recovery. When asking for help, include the experiment ID, status message, last sync time, metric type, and the mapping you expected. Keep the observed totals and underlying source available. See [reading results](https://conversionlab.app/docs/experiments/results) for interpretation once the warning is resolved. --- Source: https://conversionlab.app/docs/troubleshooting/survey-widget # Fix a survey that does not appear Check activation, installation, targeting, triggers, frequency, and competing surveys. Work through these checks on the page where the survey should appear. ## Verify the saved survey Confirm the right project and survey, save the Build and Settings changes, and set the status to **Active**. Draft, Paused, and Archived surveys do not participate in the active widget flow. ## Verify installation Copy the current project snippet from **Embed** and verify it is installed once on the website. It must belong to the project containing the survey. The snippet loads active surveys for the project, so adding another copy is not the remedy for a missing individual survey. If the script is blocked or fails to load, ask the person responsible for the website to inspect its loading error and site script policy. ## Check eligibility - **URL targeting:** does the current path match the Show rules and avoid the Hide rules? - **Trigger:** have you waited for the delay, scrolled far enough, used the button, or performed the configured action? - **Frequency:** has this browser already seen the survey within the configured interval? - **Priority:** does a higher-priority active survey also match this page? - **Appearance:** is the widget hidden behind another page element or positioned somewhere unexpected? For testing, use a fresh browser session when a frequency limit would otherwise suppress the survey. Check the actual conditions before changing production targeting for all visitors. ## Verify collection Complete the survey and inspect **Answers**, including the Submitted and Partial filters. A response that started but was not submitted can appear as Partial. If you are testing several surveys, check which one actually appeared. After verification, [reset test answers](https://conversionlab.app/docs/surveys/responses) only if you intend to delete all answers from that survey.