hanzoai 8.5.156

data/lib/hanzoai/api/content_api.rb

@@ -0,0 +1,421 @@
+=begin
+#Hanzo Cloud API
+
+#The Hanzo Cloud API as a customer calls it: every operation under /v1/ except the operator's admin product, relay routes, legacy spellings and capabilities still reached by flag. Tagged by product: the first path segment after /v1/.
+
+The version of the OpenAPI document: v1
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.14.0
+
+=end
+
+require 'cgi'
+
+module Hanzoai
+  class ContentApi
+    attr_accessor :api_client
+
+    def initialize(api_client = ApiClient.default)
+      @api_client = api_client
+    end
+    # Aggregates the caller org's marketing content across every publishable content type into ONE queue board — the cross-type read the framework's per-DocType list cannot give.
+    # Aggregates the caller org's marketing content across every publishable content type into ONE queue board — the cross-type read the framework's per-DocType list cannot give. It never fails on a partial outage: a content type the org has not installed, or one whose search errors, is skipped and logged rather than failing the whole board.
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :status Status keeps only items in one lifecycle state (draft, in_review, approved, queued, published, archived). An undefined state is refused.
+    # @option opts [String] :project Project keeps only items in one brand/site sub-scope.
+    # @option opts [String] :doctype DocType keeps only one content type; omitted, the board spans every publishable type. An unknown type is refused.
+    # @option opts [Integer] :limit Limit caps the rows returned, clamped to 1000. Defaults to 200, which is also what a non-positive or unparseable value takes.
+    # @return [BoardPage]
+    def get_content_board(opts = {})
+      data, _status_code, _headers = get_content_board_with_http_info(opts)
+      data
+    end
+
+    # Aggregates the caller org's marketing content across every publishable content type into ONE queue board — the cross-type read the framework's per-DocType list cannot give.
+    # Aggregates the caller org's marketing content across every publishable content type into ONE queue board — the cross-type read the framework's per-DocType list cannot give. It never fails on a partial outage: a content type the org has not installed, or one whose search errors, is skipped and logged rather than failing the whole board.
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :status Status keeps only items in one lifecycle state (draft, in_review, approved, queued, published, archived). An undefined state is refused.
+    # @option opts [String] :project Project keeps only items in one brand/site sub-scope.
+    # @option opts [String] :doctype DocType keeps only one content type; omitted, the board spans every publishable type. An unknown type is refused.
+    # @option opts [Integer] :limit Limit caps the rows returned, clamped to 1000. Defaults to 200, which is also what a non-positive or unparseable value takes.
+    # @return [Array<(BoardPage, Integer, Hash)>] BoardPage data, response status code and response headers
+    def get_content_board_with_http_info(opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: ContentApi.get_content_board ...'
+      end
+      # resource path
+      local_var_path = '/v1/content/board'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'status'] = opts[:'status'] if !opts[:'status'].nil?
+      query_params[:'project'] = opts[:'project'] if !opts[:'project'].nil?
+      query_params[:'doctype'] = opts[:'doctype'] if !opts[:'doctype'].nil?
+      query_params[:'limit'] = opts[:'limit'] if !opts[:'limit'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'BoardPage'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearer']
+
+      new_options = opts.merge(
+        :operation => :"ContentApi.get_content_board",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: ContentApi#get_content_board\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Lists the distribution channels the caller's org has connected — the social integrations a publish can target.
+    # Lists the distribution channels the caller's org has connected — the social integrations a publish can target. A deployment with no distribution edge wired answers 503 rather than an empty list that would read as \"no channels\".
+    # @param [Hash] opts the optional parameters
+    # @return [ChannelList]
+    def get_content_channels(opts = {})
+      data, _status_code, _headers = get_content_channels_with_http_info(opts)
+      data
+    end
+
+    # Lists the distribution channels the caller&#39;s org has connected — the social integrations a publish can target.
+    # Lists the distribution channels the caller&#39;s org has connected — the social integrations a publish can target. A deployment with no distribution edge wired answers 503 rather than an empty list that would read as \&quot;no channels\&quot;.
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(ChannelList, Integer, Hash)>] ChannelList data, response status code and response headers
+    def get_content_channels_with_http_info(opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: ContentApi.get_content_channels ...'
+      end
+      # resource path
+      local_var_path = '/v1/content/channels'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'ChannelList'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearer']
+
+      new_options = opts.merge(
+        :operation => :"ContentApi.get_content_channels",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: ContentApi#get_content_channels\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Returns the ONE marketing-content state machine: the ordered lifecycle states, which state a fresh document starts in, which one is publicly live, and the legal successors of every state.
+    # Returns the ONE marketing-content state machine: the ordered lifecycle states, which state a fresh document starts in, which one is publicly live, and the legal successors of every state. The console builds its board columns and its per-item action buttons from this single answer, so the UI and the write-time enforcement hook can never disagree about what is legal.
+    # @param [Hash] opts the optional parameters
+    # @return [StateGraph]
+    def get_content_lifecycle(opts = {})
+      data, _status_code, _headers = get_content_lifecycle_with_http_info(opts)
+      data
+    end
+
+    # Returns the ONE marketing-content state machine: the ordered lifecycle states, which state a fresh document starts in, which one is publicly live, and the legal successors of every state.
+    # Returns the ONE marketing-content state machine: the ordered lifecycle states, which state a fresh document starts in, which one is publicly live, and the legal successors of every state. The console builds its board columns and its per-item action buttons from this single answer, so the UI and the write-time enforcement hook can never disagree about what is legal.
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(StateGraph, Integer, Hash)>] StateGraph data, response status code and response headers
+    def get_content_lifecycle_with_http_info(opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: ContentApi.get_content_lifecycle ...'
+      end
+      # resource path
+      local_var_path = '/v1/content/lifecycle'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'StateGraph'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearer']
+
+      new_options = opts.merge(
+        :operation => :"ContentApi.get_content_lifecycle",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: ContentApi#get_content_lifecycle\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Moves one content item to a new lifecycle state and, on the move to published, fans it out to the item's channels.
+    # Moves one content item to a new lifecycle state and, on the move to published, fans it out to the item's channels. The edge must be legal for the item's current state — an illegal move is refused with 409 — and the status write re-validates it at the storage boundary. Distribution is best effort: its honest state is reported on the result and a distribution failure never rolls the status change back.
+    # @param doctype [String] DocType is the content type to act on, from the path.
+    # @param name [String] Name is the document to act on, from the path.
+    # @param transition_in [TransitionIn] 
+    # @param [Hash] opts the optional parameters
+    # @return [TransitionResult]
+    def post_content_by_doctype_by_name_transition(doctype, name, transition_in, opts = {})
+      data, _status_code, _headers = post_content_by_doctype_by_name_transition_with_http_info(doctype, name, transition_in, opts)
+      data
+    end
+
+    # Moves one content item to a new lifecycle state and, on the move to published, fans it out to the item&#39;s channels.
+    # Moves one content item to a new lifecycle state and, on the move to published, fans it out to the item&#39;s channels. The edge must be legal for the item&#39;s current state — an illegal move is refused with 409 — and the status write re-validates it at the storage boundary. Distribution is best effort: its honest state is reported on the result and a distribution failure never rolls the status change back.
+    # @param doctype [String] DocType is the content type to act on, from the path.
+    # @param name [String] Name is the document to act on, from the path.
+    # @param transition_in [TransitionIn] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(TransitionResult, Integer, Hash)>] TransitionResult data, response status code and response headers
+    def post_content_by_doctype_by_name_transition_with_http_info(doctype, name, transition_in, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: ContentApi.post_content_by_doctype_by_name_transition ...'
+      end
+      # verify the required parameter 'doctype' is set
+      if @api_client.config.client_side_validation && doctype.nil?
+        fail ArgumentError, "Missing the required parameter 'doctype' when calling ContentApi.post_content_by_doctype_by_name_transition"
+      end
+      # verify the required parameter 'name' is set
+      if @api_client.config.client_side_validation && name.nil?
+        fail ArgumentError, "Missing the required parameter 'name' when calling ContentApi.post_content_by_doctype_by_name_transition"
+      end
+      # verify the required parameter 'transition_in' is set
+      if @api_client.config.client_side_validation && transition_in.nil?
+        fail ArgumentError, "Missing the required parameter 'transition_in' when calling ContentApi.post_content_by_doctype_by_name_transition"
+      end
+      # resource path
+      local_var_path = '/v1/content/{doctype}/{name}/transition'.sub('{' + 'doctype' + '}', CGI.escape(doctype.to_s)).sub('{' + 'name' + '}', CGI.escape(name.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+      # HTTP header 'Content-Type'
+      content_type = @api_client.select_header_content_type(['application/json'])
+      if !content_type.nil?
+          header_params['Content-Type'] = content_type
+      end
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(transition_in)
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'TransitionResult'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearer']
+
+      new_options = opts.merge(
+        :operation => :"ContentApi.post_content_by_doctype_by_name_transition",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: ContentApi#post_content_by_doctype_by_name_transition\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Draft a piece of marketing content and file it in the CMS as a draft.
+    # Draft a piece of marketing content and file it in the CMS as a draft.  Answers 201 with the created draft's identity — {doctype, name, status} — and the document itself lands in the CMS through the SAME validate and lifecycle-hook pipeline an ordinary create runs. This is a WRITE, not a preview: there is no dry-run, and every call that succeeds leaves a document behind.  `doctype` picks which of two generation planes runs, and they are the only two. Campaign and SocialPost are drafted as brand COPY on the platform AI plane (zen5 by default, overridable per request with `model` or per deployment); Asset is a studio image render the AI plane never sees. Everything else about the call is identical.  MONEY, metered in exactly one place per mode and never both. Copy rides the platform's own inference meter — the org's balance is authorised before the model call and debited at the exact token cost after — so content never re-bills it. A studio render is invisible to that meter, so content is the sole meter for it: the org is gated BEFORE the GPU compute and refused 402 when out of funds or over its spend cap, and the debit is recorded only once the render actually returns, because the billable event is the consumed compute and not the CMS row. `project` rides the BODY rather than a server-minted identity claim, so it attributes spend but a project-scoped cap stays soft on it — the org is the value that is enforced.  The org is the caller's own, resolved once from the validated principal and never read from the body; a caller without one is refused 403. Status is not the generator's to choose: a generated item is ALWAYS a draft, and the storage-boundary hook enforces that a second time.  It fails closed rather than inventing anything. An unknown content type is 404 and a deployment whose marketing module is not installed is 409 naming the install call. An AI plane or studio that is unconfigured or unreachable, a graph the studio rejects, and a render that does not return in time all degrade to 503 — never fabricated copy, never a fake render. A `source_media` that fails the SSRF and traversal validator is 400 raised before the billing gate and before the studio is contacted, so a hostile source never costs the caller anything.
+    # @param generate_input [GenerateInput] 
+    # @param [Hash] opts the optional parameters
+    # @return [GenerateResult]
+    def post_content_generate(generate_input, opts = {})
+      data, _status_code, _headers = post_content_generate_with_http_info(generate_input, opts)
+      data
+    end
+
+    # Draft a piece of marketing content and file it in the CMS as a draft.
+    # Draft a piece of marketing content and file it in the CMS as a draft.  Answers 201 with the created draft&#39;s identity — {doctype, name, status} — and the document itself lands in the CMS through the SAME validate and lifecycle-hook pipeline an ordinary create runs. This is a WRITE, not a preview: there is no dry-run, and every call that succeeds leaves a document behind.  &#x60;doctype&#x60; picks which of two generation planes runs, and they are the only two. Campaign and SocialPost are drafted as brand COPY on the platform AI plane (zen5 by default, overridable per request with &#x60;model&#x60; or per deployment); Asset is a studio image render the AI plane never sees. Everything else about the call is identical.  MONEY, metered in exactly one place per mode and never both. Copy rides the platform&#39;s own inference meter — the org&#39;s balance is authorised before the model call and debited at the exact token cost after — so content never re-bills it. A studio render is invisible to that meter, so content is the sole meter for it: the org is gated BEFORE the GPU compute and refused 402 when out of funds or over its spend cap, and the debit is recorded only once the render actually returns, because the billable event is the consumed compute and not the CMS row. &#x60;project&#x60; rides the BODY rather than a server-minted identity claim, so it attributes spend but a project-scoped cap stays soft on it — the org is the value that is enforced.  The org is the caller&#39;s own, resolved once from the validated principal and never read from the body; a caller without one is refused 403. Status is not the generator&#39;s to choose: a generated item is ALWAYS a draft, and the storage-boundary hook enforces that a second time.  It fails closed rather than inventing anything. An unknown content type is 404 and a deployment whose marketing module is not installed is 409 naming the install call. An AI plane or studio that is unconfigured or unreachable, a graph the studio rejects, and a render that does not return in time all degrade to 503 — never fabricated copy, never a fake render. A &#x60;source_media&#x60; that fails the SSRF and traversal validator is 400 raised before the billing gate and before the studio is contacted, so a hostile source never costs the caller anything.
+    # @param generate_input [GenerateInput] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(GenerateResult, Integer, Hash)>] GenerateResult data, response status code and response headers
+    def post_content_generate_with_http_info(generate_input, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: ContentApi.post_content_generate ...'
+      end
+      # verify the required parameter 'generate_input' is set
+      if @api_client.config.client_side_validation && generate_input.nil?
+        fail ArgumentError, "Missing the required parameter 'generate_input' when calling ContentApi.post_content_generate"
+      end
+      # resource path
+      local_var_path = '/v1/content/generate'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+      # HTTP header 'Content-Type'
+      content_type = @api_client.select_header_content_type(['application/json'])
+      if !content_type.nil?
+          header_params['Content-Type'] = content_type
+      end
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(generate_input)
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'GenerateResult'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearer']
+
+      new_options = opts.merge(
+        :operation => :"ContentApi.post_content_generate",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: ContentApi#post_content_generate\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Publish distributes one CMS content item to the channels recorded on it and returns the honest per-channel outcome.
+    # Publish distributes one CMS content item to the channels recorded on it and returns the honest per-channel outcome. The item names itself — its caption, media and channel list are read from the stored document, not from this request. It is idempotent per channel (a channel already posted for this item is skipped), and a publish that loses the per-item lease to a live publisher answers status \"in_progress\" having posted nothing.
+    # @param publish_input [PublishInput] 
+    # @param [Hash] opts the optional parameters
+    # @return [PublishResult]
+    def post_content_publish(publish_input, opts = {})
+      data, _status_code, _headers = post_content_publish_with_http_info(publish_input, opts)
+      data
+    end
+
+    # Publish distributes one CMS content item to the channels recorded on it and returns the honest per-channel outcome.
+    # Publish distributes one CMS content item to the channels recorded on it and returns the honest per-channel outcome. The item names itself — its caption, media and channel list are read from the stored document, not from this request. It is idempotent per channel (a channel already posted for this item is skipped), and a publish that loses the per-item lease to a live publisher answers status \&quot;in_progress\&quot; having posted nothing.
+    # @param publish_input [PublishInput] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(PublishResult, Integer, Hash)>] PublishResult data, response status code and response headers
+    def post_content_publish_with_http_info(publish_input, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: ContentApi.post_content_publish ...'
+      end
+      # verify the required parameter 'publish_input' is set
+      if @api_client.config.client_side_validation && publish_input.nil?
+        fail ArgumentError, "Missing the required parameter 'publish_input' when calling ContentApi.post_content_publish"
+      end
+      # resource path
+      local_var_path = '/v1/content/publish'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+      # HTTP header 'Content-Type'
+      content_type = @api_client.select_header_content_type(['application/json'])
+      if !content_type.nil?
+          header_params['Content-Type'] = content_type
+      end
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(publish_input)
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'PublishResult'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearer']
+
+      new_options = opts.merge(
+        :operation => :"ContentApi.post_content_publish",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: ContentApi#post_content_publish\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+  end
+end

data/lib/hanzoai/api/crawl_api.rb

@@ -0,0 +1,90 @@
+=begin
+#Hanzo Cloud API
+
+#The Hanzo Cloud API as a customer calls it: every operation under /v1/ except the operator's admin product, relay routes, legacy spellings and capabilities still reached by flag. Tagged by product: the first path segment after /v1/.
+
+The version of the OpenAPI document: v1
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.14.0
+
+=end
+
+require 'cgi'
+
+module Hanzoai
+  class CrawlApi
+    attr_accessor :api_client
+
+    def initialize(api_client = ApiClient.default)
+      @api_client = api_client
+    end
+    # Fetch one URL and read it back as markdown
+    # Reads one URL and answers with the page as markdown.  It fetches a single URL from inside the cluster and answers with the address it actually landed on, the document's title, its content rendered to MARKDOWN, and whatever the page said about itself. One URL per call: batching would make the answer a partial-failure envelope every caller then has to unpack.  A PAGE THAT COULD NOT BE FETCHED IS A NORMAL ANSWER, not a fault. An unreachable host, a refused address and a content type that is not a document all answer 200 with `success:false` and the reason in `error`, because the caller sent a well-formed ask and gets a well-formed answer. Non-2xx is reserved for a caller problem — 400 with the same body when there is no url, 401 for a bad key, 503 when the surface is unconfigured — so error handling can trust the status. Check `success` before reading `data`.  Admission is either a validated principal or the shared service key, presented as X-API-Key or a Bearer; neither is refused, and an unset key fails closed rather than opening the fetcher to the private network. Pages are archived under the scope of the VERIFIED principal and NEVER a scope named in the body, so a URL already read under that scope is answered from the archive without touching the network; a service caller has no org and its pages land in the shared corpus.  The URL is caller-supplied and dialled from INSIDE the cluster, which makes this a request-forgery primitive by construction. Only http and https are accepted, and every address actually dialled must be public unicast — loopback, link-local, private and multicast are refused. The check lives in the DIALER rather than on the hostname, because resolving a name to validate it and then letting the transport resolve it again is a gap DNS rebinding walks straight through; redirects re-enter the same dialer.
+    # @param crawl_request [CrawlRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [CrawlResult]
+    def read_page(crawl_request, opts = {})
+      data, _status_code, _headers = read_page_with_http_info(crawl_request, opts)
+      data
+    end
+
+    # Fetch one URL and read it back as markdown
+    # Reads one URL and answers with the page as markdown.  It fetches a single URL from inside the cluster and answers with the address it actually landed on, the document's title, its content rendered to MARKDOWN, and whatever the page said about itself. One URL per call: batching would make the answer a partial-failure envelope every caller then has to unpack.  A PAGE THAT COULD NOT BE FETCHED IS A NORMAL ANSWER, not a fault. An unreachable host, a refused address and a content type that is not a document all answer 200 with `success:false` and the reason in `error`, because the caller sent a well-formed ask and gets a well-formed answer. Non-2xx is reserved for a caller problem — 400 with the same body when there is no url, 401 for a bad key, 503 when the surface is unconfigured — so error handling can trust the status. Check `success` before reading `data`.  Admission is either a validated principal or the shared service key, presented as X-API-Key or a Bearer; neither is refused, and an unset key fails closed rather than opening the fetcher to the private network. Pages are archived under the scope of the VERIFIED principal and NEVER a scope named in the body, so a URL already read under that scope is answered from the archive without touching the network; a service caller has no org and its pages land in the shared corpus.  The URL is caller-supplied and dialled from INSIDE the cluster, which makes this a request-forgery primitive by construction. Only http and https are accepted, and every address actually dialled must be public unicast — loopback, link-local, private and multicast are refused. The check lives in the DIALER rather than on the hostname, because resolving a name to validate it and then letting the transport resolve it again is a gap DNS rebinding walks straight through; redirects re-enter the same dialer.
+    # @param crawl_request [CrawlRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(CrawlResult, Integer, Hash)>] CrawlResult data, response status code and response headers
+    def read_page_with_http_info(crawl_request, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: CrawlApi.read_page ...'
+      end
+      # verify the required parameter 'crawl_request' is set
+      if @api_client.config.client_side_validation && crawl_request.nil?
+        fail ArgumentError, "Missing the required parameter 'crawl_request' when calling CrawlApi.read_page"
+      end
+      # resource path
+      local_var_path = '/v1/crawl'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+      # HTTP header 'Content-Type'
+      content_type = @api_client.select_header_content_type(['application/json'])
+      if !content_type.nil?
+          header_params['Content-Type'] = content_type
+      end
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(crawl_request)
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'CrawlResult'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearer']
+
+      new_options = opts.merge(
+        :operation => :"CrawlApi.read_page",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: CrawlApi#read_page\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+  end
+end