> ## Documentation Index
> Fetch the complete documentation index at: https://edgeful.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# revise custom report

> answer the builder's question, or change the current draft with feedback. continues the conversation from build custom report and returns what a build returns; a saved report is never edited. uses your Edgeful AI allowance, can take a few minutes and is stopped after ten. the response stays open until the work finishes or is stopped at its time limit: allow a read timeout of ten minutes, and do not send the request again while it runs. disconnecting cancels the work. a failure after the first ten seconds arrives as 200 with status failed. requires the key's write permission.



## OpenAPI

````yaml /openapi-public.json post /v1/custom-reports/drafts/{conversation_id}/revisions
openapi: 3.1.0
info:
  title: Edgeful API
  description: >-
    Public API reference for Edgeful market analysis. The bearer token is your
    Edgeful API key. Reports support the docs playground. Report responses
    include row-level output in `detailed` only when your plan includes
    row-level detail.
  version: 1.0.0
servers:
  - url: https://api.edgeful.com
    description: Production
security:
  - BearerAuth: []
tags:
  - name: reports
  - name: discovery
  - name: live data
  - name: settings
  - name: custom reports
  - name: optimizer
paths:
  /v1/custom-reports/drafts/{conversation_id}/revisions:
    post:
      tags:
        - custom reports
      summary: revise custom report
      description: >-
        answer the builder's question, or change the current draft with
        feedback. continues the conversation from build custom report and
        returns what a build returns; a saved report is never edited. uses your
        Edgeful AI allowance, can take a few minutes and is stopped after ten.
        the response stays open until the work finishes or is stopped at its
        time limit: allow a read timeout of ten minutes, and do not send the
        request again while it runs. disconnecting cancels the work. a failure
        after the first ten seconds arrives as 200 with status failed. requires
        the key's write permission.
      operationId: revise_custom_report
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: the builder conversation's id, from build custom report.
            title: Conversation Id
          description: the builder conversation's id, from build custom report.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomReportReviseRequest'
            examples:
              default:
                summary: change the draft
                value:
                  feedback: Count only upside breaks, and add a bar chart by weekday.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomReportBuildResult'
        '403':
          description: >-
            Valid API key, but the account has no API-enabled subscription or
            the key's writes are off.
          content:
            application/json:
              examples:
                missing_entitlement:
                  summary: missing entitlement
                  value:
                    detail:
                      detail: No active subscription with API access found.
                      code: missing_entitlement
                writes_disabled:
                  summary: writes disabled
                  value:
                    detail:
                      detail: >-
                        Allow changes through your API key or the MCP connector
                        in the API dashboard.
                      code: writes_disabled
        '404':
          description: no conversation has that id.
        '409':
          description: the conversation is not a custom report builder conversation.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            The account's custom report write budget is exhausted; wait
            `Retry-After` seconds. Refused attempts count too.
          content:
            application/json:
              examples:
                write_budget_exhausted:
                  summary: write budget exhausted
                  value:
                    detail:
                      detail: Custom report write limit reached. Try again shortly.
                      code: write_budget_exhausted
          headers:
            Retry-After:
              description: seconds to wait before sending the write again.
              schema:
                type: integer
        '503':
          description: The write budget could not be checked; retry shortly.
          content:
            application/json:
              examples:
                write_limits_unavailable:
                  summary: write limits unavailable
                  value:
                    detail:
                      detail: >-
                        Custom report write limits are temporarily unavailable.
                        Try again shortly.
                      code: write_limits_unavailable
      security:
        - BearerAuth: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request POST \
              --url 'https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/revisions' \
              --header 'Authorization: Bearer <api-key>' \
              --header 'Content-Type: application/json' \
              --data '{"feedback": "Count only upside breaks, and add a bar chart by weekday."}'
        - lang: python
          label: Python
          source: >-
            import requests


            url =
            "https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/revisions"

            headers = {"Authorization": "Bearer <api-key>"}

            payload = {'feedback': 'Count only upside breaks, and add a bar
            chart by weekday.'}


            response = requests.post(url, headers=headers, json=payload)

            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            const url =
            "https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/revisions";

            const options = {
              method: "POST",
              headers: { Authorization: "Bearer <api-key>", "Content-Type": "application/json" },
              body: JSON.stringify({"feedback": "Count only upside breaks, and add a bar chart by weekday."}),
            };


            const response = await fetch(url, options);

            const data = await response.json();

            console.log(data);
        - lang: php
          label: PHP
          source: >-
            <?php

            $ch =
            curl_init("https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/revisions");

            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");

            curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer
            <api-key>", "Content-Type: application/json"]);

            curl_setopt($ch, CURLOPT_POSTFIELDS, '{"feedback": "Count only
            upside breaks, and add a bar chart by weekday."}');

            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

            $response = curl_exec($ch);

            curl_close($ch);

            echo $response;
        - lang: go
          label: Go
          source: |-
            package main

            import (
                "fmt"
                "io"
                "net/http"
                "strings"
            )

            func main() {
                req, _ := http.NewRequest("POST", "https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/revisions", strings.NewReader(`{"feedback": "Count only upside breaks, and add a bar chart by weekday."}`))
                req.Header.Set("Authorization", "Bearer <api-key>")
                req.Header.Set("Content-Type", "application/json")
                resp, _ := http.DefaultClient.Do(req)
                defer resp.Body.Close()
                body, _ := io.ReadAll(resp.Body)
                fmt.Println(string(body))
            }
        - lang: java
          label: Java
          source: >-
            import java.net.URI;

            import java.net.http.HttpClient;

            import java.net.http.HttpRequest;

            import java.net.http.HttpResponse;


            HttpClient client = HttpClient.newHttpClient();

            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/revisions"))
                .header("Authorization", "Bearer <api-key>")
                .header("Content-Type", "application/json")
                .method("POST", HttpRequest.BodyPublishers.ofString("{\"feedback\": \"Count only upside breaks, and add a bar chart by weekday.\"}"))
                .build();
            HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

            System.out.println(response.body());
        - lang: ruby
          label: Ruby
          source: >-
            require "net/http"

            require "uri"


            uri =
            URI("https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/revisions")

            request = Net::HTTP::Post.new(uri)

            request["Authorization"] = "Bearer <api-key>"

            request["Content-Type"] = "application/json"

            request.body = '{"feedback": "Count only upside breaks, and add a
            bar chart by weekday."}'


            response = Net::HTTP.start(uri.hostname, uri.port, use_ssl:
            uri.scheme == "https") do |http|
              http.request(request)
            end

            puts response.body
components:
  schemas:
    CustomReportReviseRequest:
      properties:
        feedback:
          type: string
          maxLength: 25000
          minLength: 1
          title: Feedback
          description: >-
            the answer to the builder's question, or the change to make to the
            draft.
      additionalProperties: false
      type: object
      required:
        - feedback
      title: CustomReportReviseRequest
    CustomReportBuildResult:
      properties:
        status:
          type: string
          title: Status
          description: >-
            succeeded with a draft to review, needs_clarification with a
            question to answer, or failed.
        conversation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversation Id
          description: 'the builder conversation: send it to revise, run or save this draft.'
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Message Id
          description: >-
            the builder message: with status succeeded, the draft to run or
            save.
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: the builder conversation in Edgeful AI.
        question:
          anyOf:
            - type: string
            - type: 'null'
          title: Question
          description: >-
            with status needs_clarification: the question to answer in a
            revision.
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: 'with status failed: what went wrong.'
        methodology:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: how the report computes its result.
        assumptions:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: the assumptions the builder made.
        accepted_controls:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: >-
            the inputs the draft was built on: market, ticker, session, dates
            and granularity.
        sample_result:
          anyOf:
            - $ref: '#/components/schemas/CustomReportRows'
            - type: 'null'
          description: the draft's result over the builder's sample window.
        truncated:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Truncated
          description: true when a long question was shortened.
      additionalProperties: true
      type: object
      required:
        - status
      title: CustomReportBuildResult
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    JsonValue: {}
    CustomReportRows:
      properties:
        summary:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: the result's summary values.
        detailed_data:
          anyOf:
            - items:
                $ref: '#/components/schemas/JsonValue'
              type: array
            - type: 'null'
          title: Detailed Data
          description: the result's rows, every one the result holds.
        total_rows:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Rows
          description: rows in the result.
        truncated:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Truncated
          description: true when the response does not carry every row.
        column_units:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: units per column.
        row_label:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: what a row represents.
        row_grain:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: the row grain.
        presentation:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: presentation hints.
      additionalProperties: true
      type: object
      title: CustomReportRows
      description: >-
        A computed result as a client reads it: generated code and raw
        market-data rows are never part of it.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Send your Edgeful API key in the Authorization header as `Bearer
        <api-key>` (for example, `Bearer ef_live_<random>`).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.