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

# Get Database Connection

> Get PostgreSQL database connection string for your organization

Retrieve the PostgreSQL database connection details for your organization. This provides direct access to your organization's database instance for custom analytics, integrations, and data management.

## Response

<ResponseField name="id" type="string">
  Database project identifier
</ResponseField>

<ResponseField name="name" type="string">
  Database project name (typically `org_[organization_id]`)
</ResponseField>

<ResponseField name="organization_id" type="string">
  Your organization UUID
</ResponseField>

<ResponseField name="connection_uri" type="object">
  Database connection details

  <Expandable title="Connection URI Object">
    <ResponseField name="uri" type="string">
      Complete PostgreSQL connection string with credentials

      Format: `postgresql://<user>:<password>@<host>/<database>?<params>`
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

```bash theme={"dark"}
curl -X GET -H "x-api-key: <your-api-key>" \
  https://api.xpander.ai/v1/misc/db
```

## Example Response

```json theme={"dark"}
{
  "id": "still-meadow-47437464",
  "name": "org_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "organization_id": "<org-id>",
  "connection_uri": {
    "uri": "postgresql://<user>:<password>@<host>/<database>?sslmode=require"
  }
}
```

## Usage Examples

### Python (psycopg2)

```python theme={"dark"}
import psycopg2
import requests

# Get connection string
response = requests.get(
    "https://api.xpander.ai/v1/misc/db",
    headers={"x-api-key": "<your-api-key>"}
)
connection_uri = response.json()["connection_uri"]["uri"]

# Connect to database
conn = psycopg2.connect(connection_uri)
cursor = conn.cursor()

# Query data
cursor.execute("SELECT * FROM agents LIMIT 10")
results = cursor.fetchall()

cursor.close()
conn.close()
```

### Node.js (pg)

```javascript theme={"dark"}
const fetch = require('node-fetch');
const { Client } = require('pg');

// Get connection string
const response = await fetch('https://api.xpander.ai/v1/misc/db', {
  headers: { 'x-api-key': '<your-api-key>' }
});
const { connection_uri } = await response.json();

// Connect to database
const client = new Client({
  connectionString: connection_uri.uri
});
await client.connect();

// Query data
const result = await client.query('SELECT * FROM agents LIMIT 10');
console.log(result.rows);

await client.end();
```

### CLI (psql)

```bash theme={"dark"}
# Get connection string and connect
psql "$(curl -s -H 'x-api-key: <your-api-key>' \
  https://api.xpander.ai/v1/misc/db | jq -r '.connection_uri.uri')"
```

## Database Schema

Your organization database contains tables for:

* **agents** - Agent configurations and metadata
* **tasks** - Task execution records
* **knowledge\_bases** - Knowledge base metadata
* **documents** - Document records and processing status
* **users** - User information and permissions
* **organization** - Organization settings and data
* And more...

## Security Notes

* The connection string includes credentials - keep it secure
* Store the connection string as an environment variable, never in version control
* Use HTTPS only when retrieving connection strings
* The database requires SSL connections (sslmode=require)
* Be cautious with write operations to avoid accidental data modification
* Regularly rotate credentials in your organization settings

## Use Cases

* **Custom analytics** - Query task and agent data directly for reporting
* **Data export** - Extract data for external analysis and backup
* **Business intelligence** - Connect BI tools like Tableau, Metabase, Power BI
* **Integration** - Build custom integrations with third-party systems
* **Automation** - Create automated data processing pipelines
* **Advanced queries** - Perform complex SQL queries not available via REST API

## Notes

* This is a Neon PostgreSQL serverless database
* Connection pooling is handled automatically
* Database is located in AWS us-west-2 region
* SSL connections are required for security
* Connection credentials are organization-specific and should not be shared


## OpenAPI

````yaml GET /v1/misc/db
openapi: 3.1.0
info:
  title: xpander.ai API Service
  description: |2-

        The xpander.ai API Service provides a unified REST API for managing AI agents,
        executing tasks, managing knowledge bases, and integrating with external systems.
        
        Features:
        - Agent Management: Create, update, deploy, and delete AI agents
        - Task Execution: Invoke agents with support for sync, async, and streaming modes
        - Knowledge Bases: Manage knowledge bases and documents for RAG workflows
        - Tools: Discover, connect, and attach tools (connectors, custom functions, MCP servers, sub-agents, workflows) to agents and workflows
        - MCP Integration: Model Context Protocol support for standardized AI interactions
        
        Authentication: All endpoints require authentication via either an API key (`x-api-key`) or an OAuth2 JWT (`Authorization: Bearer <jwt>`).
        
  version: '0.001'
servers:
  - url: https://api.xpander.ai
security: []
paths:
  /v1/misc/db:
    get:
      tags:
        - API v1
        - Misc
        - DB
        - Postgresql
      summary: Get Db
      description: Get DB Connection string
      operationId: Get_DB_v1_misc_db_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NeonProject'
      security:
        - APIKeyHeader: []
components:
  schemas:
    NeonProject:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
        connection_uri:
          anyOf:
            - $ref: '#/components/schemas/ConnectionURIResponse'
            - type: 'null'
      type: object
      required:
        - id
        - name
      title: NeonProject
      description: >-
        Represents a Neon project used in xpander.ai for managing database
        resources.


        Attributes:
            id (str): Unique identifier for the Neon project.
            name (str): Name of the Neon project.
            organization_id (Optional[str]): The associated organization ID, inferred from the name if not provided.
            connection_uri (Optional[ConnectionURIResponse]): The connection URI for the project.
    ConnectionURIResponse:
      properties:
        uri:
          type: string
          title: Uri
      type: object
      required:
        - uri
      title: ConnectionURIResponse
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: API Key for authentication
      in: header
      name: x-api-key

````