Surf Data

https://docs.surfdata.com.br
Admin
Surf Data is a managed platform that connects PostgreSQL and MySQL databases to AI agents via Model...
Tokens:59,981
Snippets:529
Trust Score:4.4
Update:7 months ago
Show doc for...
Tokens:
Raw
### Create Datasource Example (Bash)

Source: https://docs.surfdata.com.br/pt-br/api-reference/datasources

An example using curl to demonstrate how to create a new PostgreSQL datasource. It includes the necessary headers and a JSON payload with connection configuration.

```Bash
curl -X POST https://surfdata.com.br/api/projects/clx123/datasources \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production PostgreSQL",
    "type": "postgres",
    "config": {
      "host": "db.example.com",
      "port": 5432,
      "database": "myapp",
      "username": "readonly_user",
      "password": "secure_password",
      "ssl": true
    }
  }'
```

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

### SQL Example: Agent View for Active Customers

Source: https://docs.surfdata.com.br/pt-br/concepts

An example SQL query defining an 'Agent View' in Surf Data. This view selects specific columns for active customers, demonstrating how to pre-define secure and reusable datasets for AI tools.

```sql
-- Example: Active customers view
SELECT id, name, email, plan, created_at
FROM customers
WHERE status = 'active' AND deleted_at IS NULL
```

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

### SQL Example: Parameterized Tool Query

Source: https://docs.surfdata.com.br/pt-br/concepts

An example SQL query for an MCP Tool in Surf Data, showcasing parameterized queries. This query retrieves customer details based on a provided 'customer_id', demonstrating secure data fetching with input parameters.

```sql
-- Example: Parameterized tool query
SELECT id, name, email, plan
FROM customers
WHERE id = {customer_id}
```

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

### Connection URL Examples for Datasources

Source: https://docs.surfdata.com.br/pt-br/platform/datasources

Examples of connection URLs for PostgreSQL and MySQL databases. These URLs are used to establish a connection to external data sources within the Surf Data platform. Ensure the credentials and host information are correct for your specific database.

```postgresql
postgresql://user:password@host:5432/database?sslmode=require
```

```mysql
mysql://user:password@host:3306/database
```

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

### cURL Initialization Example

Source: https://docs.surfdata.com.br/pt-br/integrations/custom-agents

Demonstrates how to initialize a connection with the Surf Data MCP endpoint using cURL. This involves sending a POST request with the 'initialize' method and necessary headers.

```bash
# Initialize
curl -X POST https://surfdata.com.br/mcp/http \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_your-token-here" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "curl-test", "version": "1.0.0"}
    },
    "id": 1
  }'
```

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

### MCP Initialize Method

Source: https://docs.surfdata.com.br/pt-br/api-reference/mcp-endpoint

Used for the initial handshake with the server to get capabilities and protocol version.

```APIDOC
## POST /mcp/http - initialize

### Description
Performs a handshake with the server to obtain its capabilities and protocol version.

### Method
POST

### Endpoint
`https://surfdata.com.br/mcp/http`

### Parameters
#### Request Body
- **jsonrpc** (string) - Specifies the JSON-RPC version, must be "2.0".
- **method** (string) - The method name, must be "initialize".
- **params** (object) - Parameters for the initialize method.
  - **protocolVersion** (string) - The desired protocol version.
  - **capabilities** (object) - Client capabilities.
  - **clientInfo** (object) - Information about the client.
    - **name** (string) - The name of the client.
    - **version** (string) - The version of the client.
- **id** (integer) - A unique identifier for the request.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-agent",
      "version": "1.0.0"
    }
  },
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - Specifies the JSON-RPC version, must be "2.0".
- **result** (object) - The result of the initialization.
  - **protocolVersion** (string) - The server's supported protocol version.
  - **capabilities** (object) - Server capabilities.
  - **serverInfo** (object) - Information about the server.
    - **name** (string) - The name of the server.
    - **version** (string) - The version of the server.
- **id** (integer) - The identifier for the request.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "surf-data-mcp",
      "version": "1.0.0"
    }
  },
  "id": 1
}
```
```

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

### SQL Query Examples with Parameters

Source: https://docs.surfdata.com.br/pt-br/platform/mcp-tools

Demonstrates SQL queries with single, multiple, and LIKE pattern parameters. These queries are designed for use with Agent Views, not raw database tables. Parameter types like string, number, boolean, and date are supported.

```sql
SELECT * FROM active_customers WHERE id = {customer_id}
```

```sql
SELECT * FROM customer_orders
WHERE customer_id = {customer_id}
  AND status = {order_status}
  AND created_at >= {start_date}
```

```sql
SELECT * FROM active_customers
WHERE name LIKE '%' || {search_term} || '%'
```

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

### Get Project

Source: https://docs.surfdata.com.br/pt-br/api-reference/projects

Retrieves a single project by its ID.

```APIDOC
## GET /api/projects/{id}

### Description
Retrieves a single project by its ID.

### Method
GET

### Endpoint
/api/projects/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the project.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
Returns the project object with full details, including relations.

#### Response Example
(Response structure is similar to the 'List Projects' success response, but for a single project.)
```

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

### API Authentication Example

Source: https://docs.surfdata.com.br/pt-br/api-reference/introduction

Example of how to authenticate with the Surf Data API using a Clerk session token.

```APIDOC
## GET /api/projects

### Description
This endpoint allows you to retrieve a list of all projects. Authentication is required.

### Method
GET

### Endpoint
https://surfdata.com.br/api/projects

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl https://surfdata.com.br/api/projects \
  -H "Cookie: __session=your-clerk-session-token"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the list of projects.

#### Response Example
```json
{
  "data": { ... }
}
```

#### Error Response (401)
- **error** (string) - Error message describing what went wrong, e.g., "Unauthorized".

#### Error Response Example
```json
{
  "error": "Unauthorized"
}
```
```

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

### Example Tool JSON Schema

Source: https://docs.surfdata.com.br/pt-br/platform/mcp-tools

Illustrates the JSON schema representation of a tool when agents call `tools/list`. This schema defines the tool's name, description, and its input parameters, including their types and whether they are required.

```json
{
  "name": "get_customer_by_id",
  "description": "Retrieves customer details by their ID",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "The unique customer identifier"
      }
    },
    "required": ["customer_id"]
  }
}
```

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

### Python Integration with MCP SDK

Source: https://docs.surfdata.com.br/pt-br/integrations/custom-agents

Example of integrating with the Surf Data MCP endpoint using a Python SDK. It demonstrates initializing the session, listing tools, and calling a tool.

```python
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": "Bearer sk_live_your-token-here"}

    async with streamablehttp_client(
        "https://surfdata.com.br/mcp/http",
        headers=headers
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[t.name for t in tools.tools]}")

            # Call a tool
            result = await session.call_tool(
                "get_customer_by_id",
                arguments={"customer_id": "12345"}
            )
            print(result)
```

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

### Node.js Integration with fetch

Source: https://docs.surfdata.com.br/pt-br/integrations/custom-agents

Example of integrating with the Surf Data MCP endpoint using Node.js and the fetch API. It shows how to construct and send JSON-RPC requests to list tools and call them.

```javascript
async function callMCP(method, params = {}) {
  const response = await fetch('https://surfdata.com.br/mcp/http', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer sk_live_your-token-here'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method,
      params,
      id: Date.now()
    })
  });
  return response.json();
}

// List tools
const tools = await callMCP('tools/list');
console.log(tools.result.tools);

// Call a tool
const result = await callMCP('tools/call', {
  name: 'get_customer_by_id',
  arguments: { customer_id: '12345' }
});
console.log(result.result);
```

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

### Listar Projetos (GET /api/projects)

Source: https://docs.surfdata.com.br/pt-br/api-reference/projects

Retorna uma lista de todos os projetos associados à organização autenticada. A resposta inclui detalhes básicos de cada projeto, como ID, nome, descrição e timestamps de criação/atualização.

```HTTP
GET /api/projects
```

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

### Tool Test Response Example

Source: https://docs.surfdata.com.br/pt-br/api-reference/tools

This JSON object represents the response received after testing a tool. It includes details about the query execution, such as the substituted query, the view used, whether PII masking was applied, and if the results were truncated.

```json
{
  "result": {
    "columns": ["id", "name", "email"],
    "rows": [
      {"id": "12345", "name": "João Silva", "email": "j***@e*****.com"}
    ],
    "rowCount": 1,
    "truncated": false,
    "executionTime": 32,
    "executedAt": "2024-01-20T14:30:00Z",
    "substitutedQuery": "SELECT id, name, email FROM active_customers WHERE id = '12345'",
    "viewUsed": "active_customers",
    "masked": true
  }
}
```

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

### Obter Projeto Específico (GET /api/projects/{id})

Source: https://docs.surfdata.com.br/pt-br/api-reference/projects

Recupera os detalhes completos de um único projeto, identificado por seu ID. Esta operação retorna o objeto do projeto com todas as suas relações e informações associadas.

```HTTP
GET /api/projects/{id}
```

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

### List Project Tools - GET /api/projects/{projectId}/tools

Source: https://docs.surfdata.com.br/pt-br/api-reference/tools

Retrieves a list of all MCP tools associated with a specific project. It requires the project ID as a path parameter and returns an array of tool objects, each containing details like ID, name, description, query, parameters, and associated IDs.

```HTTP
GET /api/projects/{projectId}/tools
```

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

### Project Publication Status Response (JSON)

Source: https://docs.surfdata.com.br/pt-br/api-reference/publishing

Example JSON response for the 'Get Project Publication Status' endpoint. It includes a boolean indicating publication status, the count of tools, and the count of active tokens.

```JSON
{
  "isPublished": true,
  "toolCount": 5,
  "activeTokenCount": 2
}
```

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

### Get MCP Server Information

Source: https://docs.surfdata.com.br/pt-br/api-reference/mcp-endpoint

This GET request retrieves metadata about the MCP server, such as its name, version, supported protocol, and authentication details. No authentication is required for this request.

```http
GET https://surfdata.com.br/mcp/http
```

```json
{
  "name": "surf-data-mcp",
  "version": "1.0.0",
  "protocol": "MCP",
  "protocolVersion": "2024-11-05",
  "authentication": {
    "type": "bearer",
    "header": "Authorization"
  }
}
```

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

### SQL View Best Practice: Using JOINs

Source: https://docs.surfdata.com.br/pt-br/platform/agent-views

Shows how to use JOIN clauses in SQL views to combine data from multiple tables, providing agents with richer context in a single query.

```sql
SELECT
  o.id as order_id,
  o.total,
  c.name as customer_name,
  p.name as product_name
FROM orders o
JOIN customers c ON c.id = o.customer_id
JOIN products p ON p.id = o.product_id
```

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

### Example Policy Code for Data Masking

Source: https://docs.surfdata.com.br/pt-br/api-reference/tools

Provides an example of the JSON structure for defining data masking policies. This policy code is used to specify which columns should have their Personally Identifiable Information (PII) masked and the type of masking to apply.

```JSON
[
  { "column": "email", "type": "email" },
  { "column": "cpf", "type": "cpf" }
]
```

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

### Create Project

Source: https://docs.surfdata.com.br/pt-br/api-reference/projects

Creates a new project within the authenticated organization.

```APIDOC
## POST /api/projects

### Description
Creates a new project within the authenticated organization.

### Method
POST

### Endpoint
/api/projects

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the project. Must be non-empty.
- **description** (string) - Optional - Optional description of the project.

### Request Example
```bash
curl -X POST https://surfdata.com.br/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Analytics Bot",
    "description": "Tools for revenue and pipeline queries"
  }'
```

### Response
#### Success Response (200)
- **id** (string) - Unique project identifier.
- **name** (string) - Project name.
- **description** (string) - Project description.
- **organizationId** (string) - ID of the owning organization.
- **createdById** (string) - ID of the user who created the project.
- **isPublished** (boolean) - Whether the project is published.
- **createdAt** (string) - Creation timestamp in ISO 8601 format.
- **updatedAt** (string) - Last update timestamp in ISO 8601 format.

#### Response Example
```json
{
  "id": "clx1234567890",
  "name": "Sales Analytics Bot",
  "description": "Tools for revenue and pipeline queries",
  "organizationId": "org_123",
  "createdById": "user_456",
  "isPublished": false,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```
```

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

### Get Tool

Source: https://docs.surfdata.com.br/pt-br/api-reference/tools

Retrieves a single tool by its ID within a specified project.

```APIDOC
## GET /api/projects/{projectId}/tools/{toolId}

### Description
Retrieves a single tool by its ID within a specified project.

### Method
GET

### Endpoint
/api/projects/{projectId}/tools/{toolId}

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The ID of the project.
- **toolId** (string) - Required - The ID of the tool to retrieve.

### Response
#### Success Response (200)
- **tool** (object) - The requested tool object.
  - **id** (string) - The unique identifier of the tool.
  - **name** (string) - The name of the tool.
  - **description** (string) - The description of the tool.
  - **query** (string) - The SQL query template.
  - **parameters** (object[]) - The parameters of the tool.
  - **viewId** (string) - The ID of the associated view.
  - **datasourceId** (string) - The ID of the associated datasource.

#### Response Example
```json
{
  "tool": {
    "id": "tool_123",
    "name": "search_customers_by_email",
    "description": "Searches for customers matching an email pattern",
    "query": "SELECT id, name, email FROM customers WHERE email LIKE {email_pattern}",
    "parameters": [
      {
        "name": "email_pattern",
        "type": "string",
        "required": true,
        "description": "Email pattern to search for"
      }
    ],
    "viewId": "view_xyz789",
    "datasourceId": "ds_abc123"
  }
}
```
```

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

### Criar Projeto (POST /api/projects)

Source: https://docs.surfdata.com.br/pt-br/api-reference/projects

Cria um novo projeto na organização autenticada. Requer um nome de projeto e opcionalmente aceita uma descrição. A resposta contém os detalhes do projeto recém-criado.

```Bash
curl -X POST https://surfdata.com.br/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Analytics Bot",
    "description": "Tools for revenue and pipeline queries"
  }'
```

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

### Exemplo de Exportação de Token em Variável de Ambiente (Bash)

Source: https://docs.surfdata.com.br/pt-br/security/tokens

Demonstra como exportar um token de acesso como uma variável de ambiente no Bash. É crucial não codificar tokens diretamente no código-fonte, mas sim utilizar variáveis de ambiente para segurança.

```bash
export SURF_DATA_TOKEN="sk_live_xxxxxxxx..."

```

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

### Connecting Agents

Source: https://docs.surfdata.com.br/pt-br/platform/publishing

Configuration examples for connecting various AI agents to the Surf Data MCP.

```APIDOC
## Conectando agentes

<Tabs>
  <Tab title="Claude Desktop">
    Adicione ao `claude_desktop_config.json`:

    ```json  theme={null}
    {
      "mcpServers": {
        "surf-data": {
          "url": "https://surfdata.com.br/mcp/http",
          "headers": {
            "Authorization": "Bearer your-token-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    Adicione ao `.mcp.json` do seu projeto:

    ```json  theme={null}
    {
      "mcpServers": {
        "surf-data": {
          "url": "https://surfdata.com.br/mcp/http",
          "headers": {
            "Authorization": "Bearer your-token-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Adicione ao `.cursor/mcp.json`:

    ```json  theme={null}
    {
      "mcpServers": {
        "surf-data": {
          "url": "https://surfdata.com.br/mcp/http",
          "headers": {
            "Authorization": "Bearer your-token-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="HTTP (direto)">
    Faça requisições JSON-RPC 2.0 diretamente:

    ```bash  theme={null}
    curl -X POST https://surfdata.com.br/mcp/http \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer your-token-here" \
      -d '{
        "jsonrpc": "2.0",
        "method": "tools/list",
        "id": 1
      }'
    ```
  </Tab>
</Tabs>

Para guias de integração detalhados, consulte:

* [Integração com Claude](/pt-br/integrations/claude)
* [Integração com Cursor](/pt-br/integrations/cursor)
* [Agentes Customizados](/pt-br/integrations/custom-agents)
```

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

### Configurar Servidor MCP Surf Data com Variável de Ambiente

Source: https://docs.surfdata.com.br/pt-br/integrations/cursor

Este snippet JSON demonstra como configurar o Surf Data como um servidor MCP no Cursor IDE, utilizando uma variável de ambiente para o Bearer token. Isso ajuda a evitar a exposição de tokens sensíveis em controle de versão.

```json
{
  "mcpServers": {
    "surf-data": {
      "url": "https://surfdata.com.br/mcp/http",
      "headers": {
        "Authorization": "Bearer ${SURF_DATA_TOKEN}"
      }
    }
  }
}
```

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

### API Response Formats

Source: https://docs.surfdata.com.br/pt-br/api-reference/introduction

Examples of success and error response formats for the Surf Data API.

```APIDOC
### Response Format

All responses utilize JSON format.

#### Success Response
```json
{
  "data": { ... }
}
```

#### Error Response
```json
{
  "error": "Error message describing what went wrong"
}
```
```

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

### Create Tool using cURL

Source: https://docs.surfdata.com.br/pt-br/api-reference/tools

This snippet demonstrates how to create a new tool within a project using a cURL command. It specifies the tool's name, description, SQL query, and parameters. The request is made to the /api/projects/{projectId}/tools endpoint with a JSON payload.

```bash
curl -X POST https://surfdata.com.br/api/projects/clx123/tools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search_customers_by_email",
    "description": "Searches for customers matching an email pattern",
    "query": "SELECT id, name, email FROM customers WHERE email LIKE {email_pattern}",
    "viewId": "view_xyz789",
    "datasourceId": "ds_abc123",
    "parameters": [
      {
        "name": "email_pattern",
        "type": "string",
        "required": true,
        "description": "Email pattern to search for"
      }
    ]
  }'
```

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

### Create Tool

Source: https://docs.surfdata.com.br/pt-br/api-reference/tools

Creates a new MCP tool within a specified project.

```APIDOC
## POST /api/projects/{projectId}/tools

### Description
Creates a new MCP tool in the project.

### Method
POST

### Endpoint
`/api/projects/{projectId}/tools`

#### Path Parameters
- **projectId** (string) - Required - The ID of the project.

#### Request Body
- **name** (string) - Required - The function name of the tool. Use snake_case (e.g., `get_customer_by_id`).
- **description** (string) - Required - Description of what the tool does. Used by AI agents to decide when to call it.
- **query** (string) - SQL query template with `{parameter}` placeholders.
- **viewId** (string) - Required - ID of the linked Agent View. Must belong to the same project.
- **datasourceId** (string) - ID of the linked datasource. Must belong to the same project.
- **parameters** (object[]) - Array of parameter definitions.
  - **name** (string) - Required - Parameter name corresponding to the `{placeholder}` in the query.
  - **type** (string) - Required - One of: `string`, `number`, `boolean`, `date`.
  - **required** (boolean) - Whether the parameter is mandatory. Default: false.
  - **description** (string) - Description for AI agents.
- **policyEnabled** (boolean) - Enable data masking policy. Default: false.
- **policyCode** (string) - JSON array of PII masking rules. Each rule maps a column to a masking type.
  Example:
  ```json
  [
    { "column": "email", "type": "email" },
    { "column": "cpf", "type": "cpf" }
  ]
  ```
  Available types: `cpf`, `cnpj`, `rg`, `email`, `phone`, `name`, `address`, `ip`, `credit_card`, `birth_date`, `salary`, `health_data`, `biometric`, `genetic`, `political_opinion`, `religious_belief`, `sexual_orientation`, `ethnic_origin`, `generic`.

### Request Example
```json
{
  "name": "get_user_orders",
  "description": "Get all orders for a specific user.",
  "query": "SELECT * FROM orders WHERE user_id = {userId}",
  "viewId": "view_abc",
  "datasourceId": "ds_xyz",
  "parameters": [
    {
      "name": "userId",
      "type": "string",
      "required": true,
      "description": "The ID of the user."
    }
  ],
  "policyEnabled": true,
  "policyCode": "[{\"column\": \"order_details\", \"type\": \"generic\"}]"
}
```

### Response
#### Success Response (200)
- **id** (string) - Required - Unique identifier for the created tool.
- **name** (string) - Required - Name of the tool.
- **description** (string) - Required - Description of the tool.
- **query** (string) - Required - SQL query template.
- **parameters** (object[]) - Required - Array of parameter definitions.
- **policyEnabled** (boolean) - Required - Whether data masking is enabled.
- **policyCode** (string) - Masking policy code.
- **viewId** (string) - Required - ID of the linked Agent View.
- **datasourceId** (string) - ID of the linked datasource.
- **projectId** (string) - Required - ID of the project.
- **createdAt** (string) - Timestamp of creation.
- **updatedAt** (string) - Timestamp of last update.

#### Response Example
```json
{
  "id": "tool_def456",
  "name": "get_user_orders",
  "description": "Get all orders for a specific user.",
  "query": "SELECT * FROM orders WHERE user_id = {userId}",
  "parameters": [
    {
      "name": "userId",
      "type": "string",
      "required": true,
      "description": "The ID of the user."
    }
  ],
  "policyEnabled": true,
  "policyCode": "[{\"column\": \"order_details\", \"type\": \"generic\"}]",
  "viewId": "view_abc",
  "datasourceId": "ds_xyz",
  "projectId": "clx1234567890",
  "createdAt": "2024-01-21T11:00:00Z",
  "updatedAt": "2024-01-21T11:00:00Z"
}
```
```

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

### Get Supplier Orders

Source: https://docs.surfdata.com.br/pt-br/examples/ecommerce-inventory-agent

Checks for pending purchase orders and deliveries from suppliers. Useful for determining when restocking will arrive.

```APIDOC
## GET /get_supplier_orders

### Description
Checks for pending purchase orders and deliveries from suppliers. Useful for determining when restocking will arrive.

### Method
GET

### Endpoint
/get_supplier_orders

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by PO status (pending, shipped, delivered).
- **supplier** (string) - Optional - Filter by supplier name.
- **limit** (string) - Optional - Defaults to "10". Number of results to retrieve.

### Request Example
```json
{
  "status": "pending",
  "supplier": "TechParts",
  "limit": "5"
}
```

### Response
#### Success Response (200)
- **po_id** (string) - The purchase order ID.
- **supplier_name** (string) - The name of the supplier.
- **status** (string) - The status of the purchase order.
- **order_date** (string) - The date the order was placed.
- **expected_delivery** (string) - The expected delivery date.
- **total_amount** (number) - The total amount of the purchase order.
- **total_items** (integer) - The total number of items in the purchase order.

#### Response Example
```json
{
  "po_id": "PO-98765",
  "supplier_name": "TechParts",
  "status": "shipped",
  "order_date": "2023-10-20T09:00:00Z",
  "expected_delivery": "2023-11-05T17:00:00Z",
  "total_amount": 1500.75,
  "total_items": 50
}
```
```

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

### GET /monthly_summary

Source: https://docs.surfdata.com.br/pt-br/examples/financial-agent

Obtains a monthly financial summary including invoiced totals, collected amounts, and outstanding balances.

```APIDOC
## GET /monthly_summary

### Description
Obtains a monthly financial summary with totals invoiced, amounts collected, and outstanding balances.

### Method
GET

### Endpoint
/monthly_summary

### Parameters
#### Query Parameters
- **period** (string, optional) - Month in YYYY-MM format
- **limit** (string, optional, default: "12") - Number of months

### Response
#### Success Response (200)
- **month** (date) - The month of the summary.
- **invoices_issued** (integer) - The number of invoices issued in the month.
- **total_invoiced** (float) - The total amount invoiced in the month.
- **total_collected** (float) - The total amount collected in the month.
- **total_outstanding** (float) - The total outstanding amount at the end of the month.
- **currency** (string) - The currency of the financial amounts.

#### Response Example
{
  "example": [
    {
      "month": "2023-11-01T00:00:00Z",
      "invoices_issued": 150,
      "total_invoiced": 75000.50,
      "total_collected": 70000.25,
      "total_outstanding": 5000.25,
      "currency": "BRL"
    }
  ]
}
```

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

### Exportar Variável de Ambiente para Token Surf Data

Source: https://docs.surfdata.com.br/pt-br/integrations/cursor

Este comando de shell exporta a variável de ambiente SURF_DATA_TOKEN, que é usada na configuração do servidor MCP do Surf Data no Cursor IDE para autenticação segura.

```bash
export SURF_DATA_TOKEN="sk_live_your-token-here"
```

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

### SQL View Best Practice: Explicit Columns

Source: https://docs.surfdata.com.br/pt-br/platform/agent-views

Demonstrates the best practice of selecting explicit columns in SQL views instead of using SELECT * for better performance and controlled data exposure.

```sql
-- Bom
SELECT id, name, email FROM customers

-- Evite
SELECT * FROM customers
```

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

### GET /ar_aging

Source: https://docs.surfdata.com.br/pt-br/examples/financial-agent

Retrieves the accounts receivable aging report, showing open amounts grouped by delinquency buckets.

```APIDOC
## GET /ar_aging

### Description
Visualizes the accounts receivable aging report. Shows open amounts grouped by delinquency buckets (current, 1-30, 30-60, 60-90, 90+ days).

### Method
GET

### Endpoint
/ar_aging

### Parameters
#### Query Parameters
- **bucket** (string, optional) - Filter by aging bucket (current, 1-30, 30-60, 60-90, 90+)
- **limit** (string, optional, default: "20") - Number of results

### Response
#### Success Response (200)
- **customer_name** (string) - Name of the customer.
- **open_invoices** (integer) - Number of open invoices for the customer.
- **total_outstanding** (float) - Total outstanding amount for the customer.
- **oldest_due_date** (date) - The oldest due date among the customer's outstanding invoices.
- **aging_bucket** (string) - The aging bucket the customer falls into.

#### Response Example
{
  "example": [
    {
      "customer_name": "Exemplo Cliente A",
      "open_invoices": 5,
      "total_outstanding": 1500.75,
      "oldest_due_date": "2023-10-15",
      "aging_bucket": "60-90"
    }
  ]
}
```

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

### GET /api/projects/{projectId}/datasources/{datasourceId}/tables

Source: https://docs.surfdata.com.br/pt-br/api-reference/datasources

Retrieves a list of tables and columns for a given datasource. You can filter by a specific table or schema.

```APIDOC
## GET /api/projects/{projectId}/datasources/{datasourceId}/tables

### Description
Retrieves the list of tables and columns from a datasource. It can filter by a specific table to get its columns or by a specific schema.

### Method
GET

### Endpoint
/api/projects/{projectId}/datasources/{datasourceId}/tables

#### Path Parameters
- **projectId** (string) - Required - The ID of the project.
- **datasourceId** (string) - Required - The ID of the datasource.

#### Query Parameters
- **table** (string) - Optional - Filter by a specific table to get its columns.
- **schema** (string) - Optional - Filter by a specific schema.

### Response
#### Success Response (200)
- **tables** (array) - List of tables with name, schema, and type.
- **columns** (array) - List of columns with name, type, and nullable information.

#### Response Example
```json
{
  "tables": [
    {
      "name": "customers",
      "schema": "public",
      "type": "table"
    }
  ],
  "columns": [
    {
      "name": "id",
      "type": "varchar",
      "nullable": false
    },
    {
      "name": "email",
      "type": "varchar",
      "nullable": false
    }
  ]
}
```
```

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

### Publish Project Response (JSON)

Source: https://docs.surfdata.com.br/pt-br/api-reference/publishing

Example JSON response for the 'Publish Project' endpoint. It confirms the success of the operation and the new publication status of the project.

```JSON
{
  "success": true,
  "isPublished": true
}
```

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

### MCP tools/list Method

Source: https://docs.surfdata.com.br/pt-br/api-reference/mcp-endpoint

Lists all available tools for the authenticated project.

```APIDOC
## POST /mcp/http - tools/list

### Description
Lists all tools available for the authenticated project.

### Method
POST

### Endpoint
`https://surfdata.com.br/mcp/http`

### Parameters
#### Request Body
- **jsonrpc** (string) - Specifies the JSON-RPC version, must be "2.0".
- **method** (string) - The method name, must be "tools/list".
- **id** (integer) - A unique identifier for the request.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 2
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - Specifies the JSON-RPC version, must be "2.0".
- **result** (object) - The result containing the list of tools.
  - **tools** (array) - An array of available tools.
    - **name** (string) - The name of the tool.
    - **description** (string) - A description of the tool.
    - **inputSchema** (object) - The schema defining the input parameters for the tool.
- **id** (integer) - The identifier for the request.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "get_customer_by_id",
        "description": "Retrieves customer details by their unique ID",
        "inputSchema": {
          "type": "object",
          "properties": {
            "customer_id": {
              "type": "string",
              "description": "The unique customer identifier"
            }
          },
          "required": ["customer_id"]
        }
      },
      {
        "name": "search_orders",
        "description": "Searches orders by customer ID and optional date range",
        "inputSchema": {
          "type": "object",
          "properties": {
            "customer_id": {
              "type": "string",
              "description": "Customer ID to search orders for"
            },
            "start_date": {
              "type": "string",
              "description": "Start date in YYYY-MM-DD format"
            }
          },
          "required": ["customer_id"]
        }
      }
    ]
  },
  "id": 2
}
```
```

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

### GET /api/projects/{projectId}/publish

Source: https://docs.surfdata.com.br/pt-br/api-reference/publishing

Retrieves the current publication status of a project, including whether it's published and counts of tools and active tokens.

```APIDOC
## GET /api/projects/{projectId}/publish

### Description
Returns the current publication status of a project.

### Method
GET

### Endpoint
/api/projects/{projectId}/publish

#### Path Parameters
- **projectId** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **isPublished** (boolean) - Whether the project is currently published.
- **toolCount** (number) - Number of MCP tools in the project.
- **activeTokenCount** (number) - Number of active access tokens.

#### Response Example
```json
{
  "isPublished": true,
  "toolCount": 5,
  "activeTokenCount": 2
}
```
```

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

### Unpublish Project Response (JSON)

Source: https://docs.surfdata.com.br/pt-br/api-reference/publishing

Example JSON response for the 'Unpublish Project' endpoint. It indicates the successful unpublishing of the project and sets the publication status to false.

```JSON
{
  "success": true,
  "isPublished": false
}
```

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

### Create Project Tool - POST /api/projects/{projectId}/tools

Source: https://docs.surfdata.com.br/pt-br/api-reference/tools

Creates a new MCP tool within a specified project. This endpoint accepts project ID as a path parameter and a JSON payload containing the tool's name, description, SQL query, view ID, datasource ID, parameters, and policy settings. The response includes the newly created tool's details.

```HTTP
POST /api/projects/{projectId}/tools
```

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

### Create Tool

Source: https://docs.surfdata.com.br/pt-br/api-reference/tools

Creates a new tool within a specified project. Tools are defined by a query, parameters, and associated datasource and view.

```APIDOC
## POST /api/projects/{projectId}/tools

### Description
Creates a new tool within a specified project. Tools are defined by a query, parameters, and associated datasource and view.

### Method
POST

### Endpoint
/api/projects/{projectId}/tools

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The ID of the project to create the tool in.

#### Request Body
- **name** (string) - Required - The name of the tool.
- **description** (string) - Optional - A description of the tool.
- **query** (string) - Required - The SQL query template for the tool.
- **viewId** (string) - Required - The ID of the view associated with the tool.
- **datasourceId** (string) - Required - The ID of the datasource associated with the tool.
- **parameters** (object[]) - Optional - An array of parameter definitions for the tool.
  - **name** (string) - Required - The name of the parameter.
  - **type** (string) - Required - The data type of the parameter.
  - **required** (boolean) - Required - Whether the parameter is required.
  - **description** (string) - Optional - A description of the parameter.

### Request Example
```json
{
  "name": "search_customers_by_email",
  "description": "Searches for customers matching an email pattern",
  "query": "SELECT id, name, email FROM customers WHERE email LIKE {email_pattern}",
  "viewId": "view_xyz789",
  "datasourceId": "ds_abc123",
  "parameters": [
    {
      "name": "email_pattern",
      "type": "string",
      "required": true,
      "description": "Email pattern to search for"
    }
  ]
}
```

### Response
#### Success Response (200)
- **tool** (object) - The created tool object.
  - **id** (string) - The unique identifier of the tool.
  - **name** (string) - The name of the tool.
  - **description** (string) - The description of the tool.
  - **query** (string) - The SQL query template.
  - **parameters** (object[]) - The parameters of the tool.
  - **viewId** (string) - The ID of the associated view.
  - **datasourceId** (string) - The ID of the associated datasource.

#### Response Example
```json
{
  "tool": {
    "id": "tool_123",
    "name": "search_customers_by_email",
    "description": "Searches for customers matching an email pattern",
    "query": "SELECT id, name, email FROM customers WHERE email LIKE {email_pattern}",
    "parameters": [
      {
        "name": "email_pattern",
        "type": "string",
        "required": true,
        "description": "Email pattern to search for"
      }
    ],
    "viewId": "view_xyz789",
    "datasourceId": "ds_abc123"
  }
}
```
```

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

### Get Target Attainment

Source: https://docs.surfdata.com.br/pt-br/examples/sales-analytics-agent

Retrieves sales target attainment data for vendors, showing target vs. actual revenue and attainment percentage.

```APIDOC
## GET /get_target_attainment

### Description
Verifica o atingimento de metas dos vendedores. Mostra meta vs. receita real e percentual de atingimento.

### Method
GET

### Endpoint
/get_target_attainment

### Parameters
#### Query Parameters
- **rep_name** (string, opcional) - Filtrar por nome do vendedor
- **period** (string, opcional) - Filtrar por periodo (ex.: "2025-Q1")

### Request Example
```json
{
  "rep_name": "John Doe",
  "period": "2025-Q1"
}
```

### Response
#### Success Response (200)
- **rep_name** (string) - Nome do vendedor
- **period** (string) - Periodo de referencia
- **target_amount** (number) - Valor da meta
- **actual_amount** (number) - Valor da receita real
- **attainment_pct** (number) - Percentual de atingimento

#### Response Example
```json
{
  "rep_name": "John Doe",
  "period": "2025-Q1",
  "target_amount": 10000.00,
  "actual_amount": 8500.00,
  "attainment_pct": 85.0
}
```
```

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

### SQL Query for Pipeline Snapshot

Source: https://docs.surfdata.com.br/en/examples/sales-analytics-agent

This SQL query retrieves details for all open deals, including deal ID, name, stage, amount, probability, expected close date, and the sales rep's name. It joins the 'deals' and 'sales_reps' tables and orders results by the expected close date.

```sql
SELECT
  d.id AS deal_id,
  d.name AS deal_name,
  d.stage,
  d.amount,
  d.probability,
  d.expected_close_date,
  d.owner_id,
  r.name AS rep_name
FROM deals d
JOIN sales_reps r ON d.owner_id = r.id
WHERE d.status = 'open'
ORDER BY d.expected_close_date ASC
```

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

### REST API Session Authentication (Bash)

Source: https://docs.surfdata.com.br/pt-br/api-reference/authentication

Example of how to authenticate with the Surf Data REST API using a Clerk session token. This requires a valid '__session' cookie in the request header.

```bash
curl -X GET https://surfdata.com.br/api/projects \
  -H "Cookie: __session=your-clerk-session-token" \
  -H "Content-Type: application/json"
```

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

### Create Datasource

Source: https://docs.surfdata.com.br/pt-br/api-reference/datasources

Creates a new database connection within a project.

```APIDOC
## POST /api/projects/{projectId}/datasources

### Description
Creates a new database connection for a project.

### Method
POST

### Endpoint
/api/projects/{projectId}/datasources

#### Path Parameters
- **projectId** (string) - Required - The ID of the project.

#### Request Body
- **name** (string) - Required - Display name for the datasource.
- **type** (string) - Required - Database type. One of: `postgres`, `mysql`, `demo`.
- **config** (object) - Connection configuration. Required for `postgres` and `mysql` types.
  - **connectionString** (string) - Full connection URL. If provided, other fields are optional.
  - **host** (string) - Database server hostname.
  - **port** (number) - Database server port. Default: 5432 (PG) or 3306 (MySQL).
  - **database** (string) - Database name.
  - **username** (string) - Database user.
  - **password** (string) - Database password.
  - **ssl** (boolean) - Enable SSL (PostgreSQL only).
  - **sslMode** (string) - SSL mode (e.g., `require`, `verify-full`).

### Request Example
```json
{
  "name": "Production PostgreSQL",
  "type": "postgres",
  "config": {
    "host": "db.example.com",
    "port": 5432,
    "database": "myapp",
    "username": "readonly_user",
    "password": "secure_password",
    "ssl": true
  }
}
```

### Process
1. Validates configuration fields.
2. Tests the database connection.
3. Encrypts the configuration.
4. Checks organization datasource limits.
5. Creates and returns the datasource.

### Errors
- **400 Bad Request**: Missing required fields or connection test failed.
- **409 Conflict**: Organization has reached its datasource limit.
```
Tokens:
Raw