### Example GET Requests with Pagination (Bash)

Source: https://docs.caesar.xyz/get-started/pagination

Demonstrates how to make GET requests to the Caesar API endpoints with specified page and limit parameters for pagination.

```bash
GET /research?page=1&limit=25
```

```bash
GET /research/files?page=2&limit=50
```

--------------------------------

### Example of Clear vs. Ambiguous Query

Source: https://docs.caesar.xyz/get-started/prompt-guidance

Demonstrates how to write a more specific query to avoid ambiguity and improve research results. The 'Better' example clarifies the domain and specific terms being queried.

```text
What are the top tokens in the virtuals agent ecosystem?
```

```text
Top virtuals tokens
```

--------------------------------

### List Research Files with Caesar Python SDK

Source: https://docs.caesar.xyz/api-reference/research/get-research-files

This example demonstrates how to use the Caesar Python SDK to list research files. It requires the caesar library to be installed. The code initializes the client with an API key and retrieves the first page of file data.

```python
from caesar import Caesar

client = Caesar(
    api_key="My API Key",
)
page = client.research.files.list()
page = page.data[0]
print(page.id)
```

--------------------------------

### Fetch Research Data using HTTP GET (Swift)

Source: https://docs.caesar.xyz/api-reference/research/get-research-objects

Illustrates how to make an HTTP GET request in Swift using URLSession. It sets up the request headers and handles the response asynchronously.

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.caesar.xyz/research?page=1&limit=10")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

--------------------------------

### Fetch Research Data using HTTP GET (C#)

Source: https://docs.caesar.xyz/api-reference/research/get-research-objects

A C# example utilizing the RestSharp library to execute an HTTP GET request against the Caesar API. It demonstrates adding the Authorization header to the request.

```csharp
var client = new RestClient("https://api.caesar.xyz/research?page=1&limit=10");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

--------------------------------

### Fetch Research Data using HTTP GET (Ruby)

Source: https://docs.caesar.xyz/api-reference/research/get-research-objects

Demonstrates fetching research data using a direct HTTP GET request in Ruby. It constructs the URL, sets up SSL, and includes an Authorization header.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.caesar.xyz/research?page=1&limit=10")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Fetch Research List using Caesar SDK (Go)

Source: https://docs.caesar.xyz/api-reference/research/get-research-objects

Provides a Go example for creating a Caesar client with an API key and fetching a list of research items. Includes basic error handling for the API call.

```go
package main

import (
  "context"
  "fmt"

  "github.com/caesar-data/go-sdk"
  "github.com/caesar-data/go-sdk/option"
)

func main() {
  client := caesar.NewClient(
    option.WithAPIKey("My API Key"),
  )
  page, err := client.Research.List(context.TODO(), caesar.ResearchListParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

--------------------------------

### Create File with Caesar SDK (Go)

Source: https://docs.caesar.xyz/api-reference/research/create-research-file

Provides a Go example for creating a file using the Caesar SDK. It sets up the client with an API key and uses a byte buffer to represent the file content. Requires the 'github.com/caesar-data/go-sdk' package.

```go
package main

import (
  "bytes"
  "context"
  "fmt"
  "io"

  "github.com/caesar-data/go-sdk"
  "github.com/caesar-data/go-sdk/option"
)

func main() {
  client := caesar.NewClient(
    option.WithAPIKey("My API Key"),
  )
  file, err := client.Research.Files.New(context.TODO(), caesar.ResearchFileNewParams{
    File: io.Reader(bytes.NewBuffer([]byte("(binary)"))),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", file.ID)
}
```

--------------------------------

### JSON Example: Market Intelligence Query with Compute Units

Source: https://docs.caesar.xyz/get-started/compute-units-cu

This JSON object shows examples of market intelligence queries, including the query description and the number of compute units allocated. It covers trend identification and comprehensive supply chain analysis, demonstrating how CU scales with analytical depth.

```json
{
  "query": "Current trends in enterprise AI adoption",
  "compute_units": 2
}

{
  "query": "Global semiconductor supply chain vulnerabilities and mitigation strategies post-2023",
  "compute_units": 7
}
```

--------------------------------

### Fetch Research Data using HTTP GET (Java)

Source: https://docs.caesar.xyz/api-reference/research/get-research-objects

An example in Java using the Unirest library to make an HTTP GET request to the Caesar API. It sets the Authorization header and retrieves the response body as a string.

```java
HttpResponse<String> response = Unirest.get("https://api.caesar.xyz/research?page=1&limit=10")
  .header("Authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### JSON Example: Financial Analysis Query with Compute Units

Source: https://docs.caesar.xyz/get-started/compute-units-cu

This JSON object demonstrates how to specify a financial analysis query along with the desired compute units. It includes examples for both earnings summaries and comparative market analysis, showing different CU requirements based on query complexity.

```json
{
  "query": "Apple Q3 2024 earnings highlights",
  "compute_units": 2
}

{
  "query": "Comparative analysis of FAANG stocks YTD performance with sector rotation implications",
  "compute_units": 5
}
```

--------------------------------

### List Research Files with Caesar Go SDK

Source: https://docs.caesar.xyz/api-reference/research/get-research-files

This Go code snippet shows how to initialize the Caesar Go SDK and list research files. It requires the caesar-data/go-sdk package. The example includes context handling and error checking for the API request.

```go
package main

import (
  "context"
  "fmt"

  "github.com/caesar-data/go-sdk"
  "github.com/caesar-data/go-sdk/option"
)

func main() {
  client := caesar.NewClient(
    option.WithAPIKey("My API Key"),
  )
  page, err := client.Research.Files.List(context.TODO(), caesar.ResearchFileListParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

--------------------------------

### POST /research

Source: https://docs.caesar.xyz/api-reference/research/create-research-object

Initiates a new research job. This endpoint allows you to start a research process by providing a search query and optionally specifying file IDs, compute units, and a system prompt.

```APIDOC
## POST /research

### Description
Start a new research job using a query and optional file IDs.

### Method
POST

### Endpoint
https://api.caesar.xyz/research

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer authentication of the form `Bearer <token>`, where token is your auth token.

#### Request Body
- **query** (string) - Required - The search query.
- **files** (array[string]) - Optional - An array of file IDs (UUIDs) to include in the research.
- **compute_units** (integer) - Optional - The number of compute units to allocate for the job.
- **system_prompt** (string) - Optional - A system prompt to guide the research process.

### Request Example
```json
{
  "query": "What are the latest advancements in AI?",
  "files": ["a1b2c3d4-e5f6-7890-1234-567890abcdef"],
  "compute_units": 10,
  "system_prompt": "Focus on ethical implications."
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier (UUID) of the created research job.
- **status** (string) - The current status of the research job. Possible values include: `queued`, `searching`, `summarizing`, `analyzing`, `completed`, `failed`, `researching`.

#### Response Example
```json
{
  "id": "f1e2d3c4-b5a6-7890-1234-567890fedcba",
  "status": "queued"
}
```
```

--------------------------------

### JSON Example: Scientific Research Query with Compute Units

Source: https://docs.caesar.xyz/get-started/compute-units-cu

This JSON object illustrates how to structure scientific research queries, specifying the research topic and the allocated compute units. Examples cover recent breakthroughs and systematic meta-analysis, highlighting varying CU needs for different research depths.

```json
{
  "query": "Recent breakthroughs in CRISPR gene editing 2024",
  "compute_units": 3
}

{
  "query": "Meta-analysis of quantum computing applications in drug discovery with commercial viability assessment",
  "compute_units": 8
}
```

--------------------------------

### Fetch Research Files via HTTP GET Request (PHP)

Source: https://docs.caesar.xyz/api-reference/research/get-research-files

This PHP example uses the Guzzle HTTP client to make a GET request to the Caesar API to retrieve research files. It demonstrates setting the `Authorization` header for authentication and accessing the response body.

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.caesar.xyz/research/files?page=1&limit=10', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

--------------------------------

### Create Research Query with SDK (Go)

Source: https://docs.caesar.xyz/api-reference/research/create-research-object

Provides an example of creating a research query using the Caesar Go SDK. It depends on the 'github.com/caesar-data/go-sdk' package and requires an API key. The input is a query string, and the output is the research ID.

```go
package main

import (
  "context"
  "fmt"

  "github.com/caesar-data/go-sdk"
  "github.com/caesar-data/go-sdk/option"
)

func main() {
  client := caesar.NewClient(
    option.WithAPIKey("My API Key"),
  )
  research, err := client.Research.New(context.TODO(), caesar.ResearchNewParams{
    Query: "Is lithium supply a bottleneck for EV adoption?",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", research.ID)
}
```

--------------------------------

### Example Error Response for Invalid Pagination (JSON)

Source: https://docs.caesar.xyz/get-started/pagination

Shows an example JSON error response when invalid pagination parameters are provided to the Caesar API.

```json
{
  "error": {
    "code": "INVALID_PAGINATION",
    "message": "Invalid pagination parameters: page must be >= 1",
    "details": {
      "page": 0,
      "limit": 10
    }
  }
}
```

--------------------------------

### Fetch Research Files via HTTP GET Request (Ruby)

Source: https://docs.caesar.xyz/api-reference/research/get-research-files

This Ruby script demonstrates how to fetch research files by making a direct HTTP GET request to the Caesar API. It uses the built-in `net/http` and `uri` libraries. Authentication is handled via a Bearer token in the Authorization header.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.caesar.xyz/research/files?page=1&limit=10")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Example Paginated API Response (JSON)

Source: https://docs.caesar.xyz/get-started/pagination

Illustrates the structure of a typical paginated response from the Caesar API, including the 'data' array and 'pagination' metadata.

```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "has_next": true
  }
}
```

--------------------------------

### Authenticate Request with Bearer Token (curl)

Source: https://docs.caesar.xyz/get-started/authentication

This example demonstrates how to authenticate a request to the Caesar API using a Bearer token. The API key should be stored securely, for example, as an environment variable ($CAESAR_API_KEY), and passed in the `Authorization` header.

```Bash
curl 'https://api.caesar.xyz/research?page=1&limit=25' \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Accept: application/json"
```

--------------------------------

### Fetch Research Files via HTTP GET Request (Swift)

Source: https://docs.caesar.xyz/api-reference/research/get-research-files

This Swift code demonstrates making an HTTP GET request to retrieve research files using `URLSession`. It configures an `NSMutableURLRequest` with the target URL, sets the `Authorization` header, and initiates a data task to handle the network request and response.

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.caesar.xyz/research/files?page=1&limit=10")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

--------------------------------

### Upload File via HTTP POST (Swift)

Source: https://docs.caesar.xyz/api-reference/research/create-research-file

A Swift example demonstrating an HTTP POST request for file uploads using URLSession. It configures headers and prepares the request body. This snippet requires further implementation for actual file content handling.

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "multipart/form-data; boundary=---011000010111000001101001"
]
let parameters = []

let boundary = "---011000010111000001101001"

var body = ""
var error: NSError? = nil
for param in parameters {
  let paramName = param["name"]!
  body += "--\(boundary)\r\n"
  body += "Content-Disposition:form-data; name=\"\(paramName)\""
  if let filename = param["fileName"] {
    let contentType = param["content-type"]!
    let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
    if (error != nil) {
      print(error as Any)
    }
    body += "; filename=\"\(filename)\"\r\n"
    body += "Content-Type: \(contentType)\r\n\r\n"
    body += fileContent
  } else if let paramValue = param["value"] {
    body += "\r\n\r\n\(paramValue)"
  }
}

let request = NSMutableURLRequest(url: NSURL(string: "https://api.caesar.xyz/research/files")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

--------------------------------

### Upload File via HTTP POST (PHP)

Source: https://docs.caesar.xyz/api-reference/research/create-research-file

A PHP example using GuzzleHttp to send a POST request for file uploads. It configures the necessary Authorization and Content-Type headers. Requires the GuzzleHttp client library.

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.caesar.xyz/research/files', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'multipart/form-data; boundary=---011000010111000001101001',
  ],
]);

echo $response->getBody();
```

--------------------------------

### Create Research File with Python

Source: https://docs.caesar.xyz/api-reference/research/create-research-file_explorer=true

This snippet provides a Python example for uploading a file to create a research file. It uses the 'requests' library to send a POST request, including the Authorization header and multipart/form-data. Ensure you replace '<token>' with your valid bearer token and provide the correct file path.

```Python
import requests

def create_research_file(file_path: str, token: str):
    url = "https://api.caesar.xyz/research/files"
    headers = {
        "Authorization": f"Bearer {token}"
    }
    with open(file_path, 'rb') as f:
        files = {'file': f}
        response = requests.post(url, headers=headers, files=files)
    
    response.raise_for_status()  # Raise an exception for bad status codes
    return response.json()

# Example usage:
# file_to_upload = "/path/to/your/document.pdf"
# bearer_token = "<your_token>"
# try:
#     result = create_research_file(file_to_upload, bearer_token)
#     print(result)
# except requests.exceptions.RequestException as e:
#     print(f"Error: {e}")
```

--------------------------------

### Upload File via HTTP POST (Ruby)

Source: https://docs.caesar.xyz/api-reference/research/create-research-file

A Ruby snippet demonstrating how to upload a file using Net::HTTP. It constructs a POST request with appropriate headers for multipart form data. Note: This example does not include actual file content in the body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.caesar.xyz/research/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body
```

--------------------------------

### Make Research API POST Request (Java)

Source: https://docs.caesar.xyz/api-reference/research/create-research-object

An example in Java using the Unirest library to send a POST request to the Caesar API for creating a research query. It requires an API token for authentication and sends the query in the JSON request body.

```java
HttpResponse<String> response = Unirest.post("https://api.caesar.xyz/research")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"Is lithium supply a bottleneck for EV adoption?\"\n}")
  .asString();
```

--------------------------------

### Make Research API POST Request (C#)

Source: https://docs.caesar.xyz/api-reference/research/create-research-object

A C# example using the RestSharp library to send a POST request to the Caesar API for creating research queries. It sets the authorization header and content type, and prepares the request for execution.

```csharp
var client = new RestClient("https://api.caesar.xyz/research");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
```

--------------------------------

### OpenAPI Specification for Listing Research Files

Source: https://docs.caesar.xyz/api-reference/research/get-research-files

This OpenAPI 3.1.1 specification defines the 'GET /research/files' endpoint. It outlines the request parameters (pagination, authorization) and the structure of the successful response, including file details and pagination information. It also details potential error responses.

```yaml
openapi: 3.1.1
info:
  title: Get Research Files
  version: endpoint_research.getResearchFiles
paths:
  /research/files:
    get:
      operationId: get-research-files
      summary: Get Research Files
      description: Returns a paginated list of Research File objects.
      tags:
        - - subpackage_research
      parameters:
        - name: page
          in: query
          description: 1-based page index.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: Page size (items per page).
          required: false
          schema:
            type: integer
        - name: Authorization
          in: header
          description: >-
            Bearer authentication of the form `Bearer <token>`, where token is
            your auth token.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Research_getResearchFiles_Response_200'
        '401':
          description: Unauthorized — invalid or missing API key.
          content: {}
        '500':
          description: Internal server error.
          content: {}
components:
  schemas:
    ResearchFilesGetResponsesContentApplicationJsonSchemaDataItems:
      type: object
      properties:
        id:
          type: string
          format: uuid
        file_name:
          type: string
        content_type:
          type: string
      required:
        - id
        - file_name
        - content_type
    ResearchFilesGetResponsesContentApplicationJsonSchemaPagination:
      type: object
      properties:
        limit:
          type: integer
        page:
          type: integer
        has_next:
          type: boolean
        total:
          type: integer
      required:
        - limit
        - page
        - has_next
    Research_getResearchFiles_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: >-
              #/components/schemas/ResearchFilesGetResponsesContentApplicationJsonSchemaDataItems
        pagination:
          $ref: >-
            #/components/schemas/ResearchFilesGetResponsesContentApplicationJsonSchemaPagination
      required:
        - data
        - pagination

```

--------------------------------

### System Prompt for Technical Brief Transformation

Source: https://docs.caesar.xyz/get-started/prompt-guidance

Provides a JSON configuration for the 'system_prompt' to focus the output on technical specifications, implementation details, and comparative metrics.

```json
{
  "system_prompt": "Focus on technical specifications, implementation details, and comparative metrics"
}
```

--------------------------------

### System Prompt for Executive Summary Transformation

Source: https://docs.caesar.xyz/get-started/prompt-guidance

Provides a JSON configuration for the 'system_prompt' to generate a 3-paragraph executive summary, including key insights, implications, and recommendations.

```json
{
  "system_prompt": "Provide a 3-paragraph executive summary highlighting key insights, implications, and recommendations"
}
```

--------------------------------

### List Research Files (Python)

Source: https://docs.caesar.xyz/api-reference/research/get-research-files_explorer=true

This snippet provides a Python example for listing research files. It uses the 'requests' library to send a GET request with the necessary Authorization header and pagination query parameters. The function returns the JSON response containing file data.

```python
import requests

def list_research_files(token: str, page: int = 1, limit: int = 10):
    headers = {
        'Authorization': f'Bearer {token}'
    }
    params = {
        'page': page,
        'limit': limit
    }
    response = requests.get('https://api.caesar.xyz/research/files', headers=headers, params=params)
    response.raise_for_status()  # Raise an exception for bad status codes
    return response.json()
```

--------------------------------

### Retrieve Research Result Content via HTTP (C#)

Source: https://docs.caesar.xyz/api-reference/research/get-research-result-content

This C# example demonstrates fetching raw research result content using the RestSharp library. It constructs a GET request to the API endpoint and adds the required Authorization header. The response is then executed and can be processed.

```csharp
var client = new RestClient("https://api.caesar.xyz/research/id/results/resultId/content");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

--------------------------------

### Retrieve Raw Research Result Content (TypeScript)

Source: https://docs.caesar.xyz/api-reference/research/get-research-result-content_explorer=true

Example of how to retrieve raw research result content using TypeScript. This involves making a GET request to the specified API endpoint with the necessary authorization token and path parameters. The function is designed to handle the response containing the raw content.

```typescript
async function getRawResearchResultContent(id: string, resultId: string, token: string): Promise<string> {
  const response = await fetch(`https://api.caesar.xyz/research/${id}/results/${resultId}/content`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const data = await response.json();
  return data.content;
}
```

--------------------------------

### System Prompt for Structured Analysis Transformation

Source: https://docs.caesar.xyz/get-started/prompt-guidance

Provides a JSON configuration for the 'system_prompt' to structure the response into distinct sections: Overview, Key Findings, Market Impact, and Future Outlook.

```json
{
  "system_prompt": "Structure the response with sections: Overview, Key Findings, Market Impact, Future Outlook"
}
```

--------------------------------

### System Prompt for Investment Perspective Transformation

Source: https://docs.caesar.xyz/get-started/prompt-guidance

Provides a JSON configuration for the 'system_prompt' to analyze research results from an investment viewpoint, covering opportunities, risks, and market dynamics.

```json
{
  "system_prompt": "Analyze from an investment perspective, highlighting opportunities, risks, and market dynamics"
}
```

--------------------------------

### Fetch Research Files via HTTP GET Request (C#)

Source: https://docs.caesar.xyz/api-reference/research/get-research-files

This C# snippet utilizes the RestSharp library to perform an HTTP GET request for fetching research files. It shows how to configure the client, set the request method to GET, and add the required `Authorization` header.

```csharp
var client = new RestClient("https://api.caesar.xyz/research/files?page=1&limit=10");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

--------------------------------

### Upload File with Caesar SDK (Python)

Source: https://docs.caesar.xyz/api-reference/research/create-research-file

Shows how to upload a file using the Caesar SDK in Python. It initializes the client with an API key and sends binary file data. Requires the 'caesar' Python package.

```python
from caesar import Caesar

client = Caesar(
    api_key="My API Key",
)
file = client.research.files.create(
    file=b"(binary)",
)
print(file.id)
```

--------------------------------

### Fetch Research Data using HTTP GET (PHP)

Source: https://docs.caesar.xyz/api-reference/research/get-research-objects

This PHP snippet uses the Guzzle HTTP client to perform a GET request to the Caesar API. It configures the necessary headers, including Authorization.

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.caesar.xyz/research?page=1&limit=10', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

--------------------------------

### POST /research Endpoint

Source: https://docs.caesar.xyz/get-started/prompt-guidance

This endpoint performs research based on a query and allows for output transformation using an optional system_prompt.

```APIDOC
## POST /research

### Description
This endpoint initiates a research task based on a provided query. It can optionally accept a `system_prompt` to format the output of the research.

### Method
POST

### Endpoint
/research

### Parameters
#### Query Parameters
None

#### Request Body
- **query** (string) - Required - The research question or topic.
- **system_prompt** (string) - Optional - A prompt to guide the output format of the research results.

### Request Example
```json
{
  "query": "Latest developments in quantum computing for drug discovery",
  "system_prompt": "Format the response as a bullet-point executive summary with key findings and implications"
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the research task.
- **status** (string) - The current status of the research task (e.g., "completed").
- **query** (string) - The original research query.
- **content** (string) - The full, untransformed research content.
- **transformed_content** (string) - The research content transformed according to the `system_prompt`.
- **results** (array) - Additional structured results or data.

#### Response Example
```json
{
  "id": "abc123...",
  "status": "completed",
  "query": "Latest developments in quantum computing for drug discovery",
  "content": "Full research content with detailed analysis...",
  "transformed_content": " Key Finding 1: IBM's quantum advantage in molecular simulation...\n" Key Finding 2: ...",
  "results": []
}
```
```

--------------------------------

### Fetch Research Files via HTTP GET Request (Java)

Source: https://docs.caesar.xyz/api-reference/research/get-research-files

This Java code snippet shows how to fetch research files using the Unirest library for making HTTP requests. It performs a GET request to the API endpoint and includes the Authorization header for authentication. The response is received as a String.

```java
HttpResponse<String> response = Unirest.get("https://api.caesar.xyz/research/files?page=1&limit=10")
  .header("Authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### Fetch Research List using Caesar SDK (Python)

Source: https://docs.caesar.xyz/api-reference/research/get-research-objects

Shows how to use the Caesar Python SDK to instantiate a client and retrieve the first research item from the list. It accesses the data directly from the response object.

```python
from caesar import Caesar

client = Caesar(
    api_key="My API Key",
)
page = client.research.list()
page = page.data[0]
print(page.id)
```

--------------------------------

### Response Structure with Transformed Content

Source: https://docs.caesar.xyz/get-started/prompt-guidance

Illustrates the JSON response structure when a 'system_prompt' is used. It includes the original 'content' and the 'transformed_content' based on the system prompt.

```json
{
  "id": "abc123...",
  "status": "completed",
  "query": "Latest developments in quantum computing for drug discovery",
  "content": "Full research content with detailed analysis...",
  "transformed_content": "" Key Finding 1: IBM's quantum advantage in molecular simulation...\n" Key Finding 2: ...",
  "results": [...] 
}
```

--------------------------------

### Create Research

Source: https://docs.caesar.xyz/api-reference/research/create-research-object_explorer=true

Initiates a new research job with a query and optional file IDs, compute units, and a system prompt.

```APIDOC
## POST /research

### Description
Start a new research job using a query and optional file IDs.

### Method
POST

### Endpoint
https://api.caesar.xyz/research

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **querystring** (string) - Required - Primary research question or instruction.
- **files** (list of strings) - Optional - IDs of previously uploaded files to include.
- **compute_units** (integer) - Optional - Optional compute budget for the job. Defaults to 1. (>=1, <=10)
- **system_prompt** (string) - Optional - Optional system prompt to steer the assistant.

### Request Example
```json
{
  "querystring": "What is the impact of climate change on coastal erosion?",
  "files": ["file_id_1", "file_id_2"],
  "compute_units": 2,
  "system_prompt": "Focus on scientific research papers."
}
```

### Response
#### Success Response (200)
- **id** (string) - Research job identifier (UUID format).
- **status** (enum) - Current status of the research job.

#### Response Example
```json
{
  "id": "f2f6e5db-2c7d-4f56-bb0c-5a6b6a7a9b10",
  "status": "queued"
}
```

### Errors
- **400**: Bad Request Error
- **401**: Unauthorized Error
- **429**: Too Many Requests Error
- **500**: Internal Server Error
```

--------------------------------

### GET /research/files

Source: https://docs.caesar.xyz/api-reference/research/get-research-files_explorer=true

Retrieves a paginated list of research files. Supports filtering by page and limit.

```APIDOC
## GET /research/files

### Description
Retrieves a paginated list of Research File objects.

### Method
GET

### Endpoint
https://api.caesar.xyz/research/files

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Defaults to `1`. `_>=1`.
  1-based page index.
- **limit** (integer) - Optional - Defaults to `10`. `<=200`, `>=1`.
  Page size (items per page).

### Request Example
```bash
curl -G https://api.caesar.xyz/research/files \
     -H "Authorization: Bearer <token>" \
     -d page=1 \
     -d limit=10
```

### Response
#### Success Response (200)
- **data** (list of objects) - List of file objects.
  - **id** (string) - Unique identifier for the file.
  - **file_name** (string) - The name of the file.
  - **content_type** (string) - The MIME type of the file.
- **pagination** (object) - Pagination details.
  - **limit** (integer) - The limit applied to the current page.
  - **page** (integer) - The current page number.
  - **has_next** (boolean) - Indicates if there are more pages.

#### Response Example
```json
{
  "data": [
    {
      "id": "9c6f8b1a-2a4f-4a35-86b9-0d0b5e25d5e5",
      "file_name": "document.pdf",
      "content_type": "application/pdf"
    },
    {
      "id": "1a2b3c4d-1111-2222-3333-444455556666",
      "file_name": "notes.txt",
      "content_type": "text/plain"
    }
  ],
  "pagination": {
    "limit": 10,
    "page": 1,
    "has_next": true
  }
}
```

### Errors
- **401** - Unauthorized Error
- **500** - Internal Server Error
```

--------------------------------

### Create File with Caesar SDK (TypeScript)

Source: https://docs.caesar.xyz/api-reference/research/create-research-file

Demonstrates how to create a file using the Caesar SDK in TypeScript. It initializes the client with an API key and uploads a file stream. Requires the 'caesar-data' package and Node.js 'fs' module.

```typescript
import Caesar from 'caesar-data';

const client = new Caesar({
  apiKey: 'My API Key',
});

const file = await client.research.files.create({ file: fs.createReadStream('path/to/file') });

console.log(file.id);
```

--------------------------------

### GET /research/{id}

Source: https://docs.caesar.xyz/api-reference/research/get-research-object

Retrieve a single research object by its unique ID. This endpoint requires an Authorization header for authentication.

```APIDOC
## GET /research/{id}

### Description
Retrieve a single research object by ID.

### Method
GET

### Endpoint
`/research/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the research object.

#### Header Parameters
- **Authorization** (string) - Required - Bearer authentication token in the format `Bearer <token>`.

### Request Example
```json
{
  "example": "GET https://api.caesar.xyz/research/some-research-id"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the research object.
- **created_at** (string) - The timestamp when the research object was created.
- **status** (string) - The current status of the research object (e.g., 'completed', 'failed').
- **query** (string) - The original query used to retrieve the research object.
- **content** (string | null) - The raw content of the research object, if available.
- **transformed_content** (string | null) - The transformed content of the research object, if available.
- **results** (array) - A list of research results associated with the object.
  - **id** (string) - The ID of a specific result.
  - **score** (number) - The relevance score of the result.
  - **title** (string) - The title of the result.
  - **url** (string) - The URL of the result.
  - **citation_index** (integer) - The citation index of the result.

#### Response Example
```json
{
  "example": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "created_at": "2023-10-27T10:00:00Z",
    "status": "completed",
    "query": "latest advancements in AI",
    "content": "Some raw content here...",
    "transformed_content": "Transformed content here...",
    "results": [
      {
        "id": "result-uuid-1",
        "score": 0.95,
        "title": "Breakthroughs in Neural Networks",
        "url": "http://example.com/paper1",
        "citation_index": 150
      }
    ]
  }
}
```

#### Error Responses
- **401** - Unauthorized — invalid or missing API key.
- **404** - Resource not found.
- **500** - Internal server error.
```

--------------------------------

### Request Body for Research with System Prompt

Source: https://docs.caesar.xyz/get-started/prompt-guidance

Shows the JSON request body for the POST /research endpoint, including the 'query' and the optional 'system_prompt' parameter to specify the desired output format.

```json
{
  "query": "Latest developments in quantum computing for drug discovery",
  "system_prompt": "Format the response as a bullet-point executive summary with key findings and implications"
}
```

--------------------------------

### GET /research - List Research

Source: https://docs.caesar.xyz/api-reference/research/get-research-objects_explorer=true

Retrieves a paginated list of research objects. Supports filtering by page and limit.

```APIDOC
## GET /research

### Description
Returns a paginated list of research objects.

### Method
GET

### Endpoint
https://api.caesar.xyz/research

### Parameters
#### Query Parameters
- **page** (integer) - Optional - `_>=1_` Defaults to `1`. 1-based page index.
- **limit** (integer) - Optional - `_>=1, <=200_` Defaults to `10`. Page size (items per page).

### Request Example
```bash
curl -G https://api.caesar.xyz/research \
     -H "Authorization: Bearer <token>" \
     -d page=1 \
     -d limit=10
```

### Response
#### Success Response (200)
- **data** (list of objects) - List of research objects.
- **pagination** (object) - Pagination details including limit, page, and has_next.

#### Response Example
```json
{
  "data": [
    {
      "id": "f2f6e5db-2c7d-4f56-bb0c-5a6b6a7a9b10",
      "created_at": "2025-09-14T12:00:00Z",
      "status": "queued",
      "query": "Is lithium supply a bottleneck for EV adoption?",
      "results": []
    },
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "created_at": "2025-09-13T18:21:37Z",
      "status": "completed",
      "query": "Summarise key findings from these docs",
      "results": [
        {
          "id": "string",
          "score": 0.92,
          "title": "IEA Global EV Outlook 2025",
          "url": "https://www.iea.org/reports/global-ev-outlook-2025",
          "citation_index": 1
        }
      ],
      "content": "Final synthesis text…"
    }
  ],
  "pagination": {
    "limit": 10,
    "page": 1,
    "has_next": true
  }
}
```

### Errors
- **401** Unauthorized Error
- **500** Internal Server Error
```

--------------------------------

### List Research Files with Caesar TypeScript SDK

Source: https://docs.caesar.xyz/api-reference/research/get-research-files

This snippet shows how to initialize the Caesar SDK with an API key and iterate through research files. It automatically handles pagination for fetching multiple pages of results. No external libraries beyond the SDK are required.

```typescript
import Caesar from 'caesar-data';

const client = new Caesar({
  apiKey: 'My API Key',
});

// Automatically fetches more pages as needed.
for await (const fileListResponse of client.research.files.list()) {
  console.log(fileListResponse.id);
}
```

--------------------------------

### GET /research/files

Source: https://docs.caesar.xyz/api-reference/research/get-research-files

Retrieves a paginated list of research file objects. Supports filtering by page and limit, and requires authorization.

```APIDOC
## GET /research/files

### Description
Returns a paginated list of Research File objects.

### Method
GET

### Endpoint
https://api.caesar.xyz/research/files

### Parameters
#### Query Parameters
- **page** (integer) - Optional - 1-based page index.
- **limit** (integer) - Optional - Page size (items per page).
#### Header Parameters
- **Authorization** (string) - Required - Bearer authentication of the form `Bearer <token>`, where token is your auth token.

### Response
#### Success Response (200)
- **data** (array) - An array of Research File objects. Each object has:
  - **id** (string) - UUID of the file.
  - **file_name** (string) - The name of the file.
  - **content_type** (string) - The MIME type of the file.
- **pagination** (object) - Pagination details:
  - **limit** (integer) - The page size.
  - **page** (integer) - The current page number.
  - **has_next** (boolean) - Indicates if there is a next page.
  - **total** (integer) - The total number of items.

#### Error Response (401)
- **description** (string) - Unauthorized — invalid or missing API key.

#### Error Response (500)
- **description** (string) - Internal server error.

### Response Example
```json
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "file_name": "document.pdf",
      "content_type": "application/pdf"
    }
  ],
  "pagination": {
    "limit": 10,
    "page": 1,
    "has_next": true,
    "total": 50
  }
}
```
```

--------------------------------

### GET /research - List Research Items

Source: https://docs.caesar.xyz/get-started/pagination

Retrieves a paginated list of research items. Supports 'page' and 'limit' query parameters for controlling the results.

```APIDOC
## GET /research

### Description
Retrieves a paginated list of research items. You can specify the page number and the number of items per page.

### Method
GET

### Endpoint
/research

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve (1-based indexing). Defaults to 1. Minimum value is 1.
- **limit** (integer) - Optional - The number of items to return per page. Defaults to 10. Range is 1-200.

### Request Example
```json
{
  "request": "GET /research?page=1&limit=25"
}
```

### Response
#### Success Response (200)
- **data** (array) - An array of research items for the current page.
- **pagination** (object) - Metadata about the pagination.
  - **page** (integer) - The current page number.
  - **limit** (integer) - The number of items per page.
  - **has_next** (boolean) - Indicates if there are more pages available.

#### Response Example
```json
{
  "data": [
    {
      "id": "research-item-1",
      "title": "Example Research"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "has_next": true
  }
}
```

### Error Handling
- **Invalid page** (400) - If `page` is less than 1.
- **Invalid limit** (400) - If `limit` is less than 1 or greater than 200.
- **Invalid type** (400) - If `page` or `limit` are not integers.
```

--------------------------------

### Summarize Documents POST Request (Ruby)

Source: https://docs.caesar.xyz/api-reference/research/create-research-object

This Ruby snippet demonstrates a POST request to the Caesar XYZ API for summarizing documents. It sets authorization and content-type headers, and includes query, files, compute_units, and system_prompt in the JSON body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.caesar.xyz/research")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"Summarise key findings from these docs\",\n  \"files\": [\n    \"9c6f8b1a-2a4f-4a35-86b9-0d0b5e25d5e5\",\n    \"1a2b3c4d-1111-2222-3333-444455556666\"\n  ],\n  \"compute_units\": 3,\n  \"system_prompt\": \"You are a concise financial analyst.\"\n}"

response = http.request(request)
puts response.read_body
```

--------------------------------

### GET /research/:id/results/:resultId/content

Source: https://docs.caesar.xyz/api-reference/research/get-research-result-content_explorer=true

Retrieves the raw content for a specific result within a research object. Requires Bearer token authentication.

```APIDOC
## GET /research/:id/results/:resultId/content

### Description
Retrieves the raw content for a specific result within a research object.

### Method
GET

### Endpoint
https://api.caesar.xyz/research/:id/results/:resultId/content

### Parameters
#### Path Parameters
- **id** (string) - Required - Research job identifier (uuid).
- **resultId** (string) - Required - Result item identifier (uuid).

#### Request Body
None

### Request Example
```bash
curl -H "Authorization: Bearer <token>" https://api.caesar.xyz/research/id/results/resultId/content
```

### Response
#### Success Response (200)
- **content** (string) - Raw extracted content for this result (may include HTML, markdown, or plain text).

#### Response Example
```json
{
  "content": "Skip to main contentEnable accessibility for low visionOpen the accessibility menu\n\n![Spinner: White decorative](https://cdn.userway.org/widgetapp/images/spin_wh.svg)\n\n... (truncated) ...\nCurrent]\n"
}
```

### Errors
- **401** - Unauthorized Error
- **404** - Not Found Error
- **500** - Internal Server Error
```