Pica Passthrough API

Complete REST API for managing integrations, connections, and executing actions across 200+ platforms.

Overview

The Pica API provides:

• Core API – Manage connectors, actions, and connections
• Passthrough API – Execute any action on connected platforms
• Vault API – Manage user connections and credentials

Base URL: https://api.picaos.com

Authentication

All requests require the x-pica-secret header with your API key.

curl https://api.picaos.com/v1/available-connectors \
  -H "x-pica-secret: YOUR_API_KEY"

Getting Your API Key

1. Create account at https://app.picaos.com
2. Go to Settings > API Keys
3. Copy your secret key

Environments

API keys are environment-specific and cannot be transferred between environments.

Core API

List Available Connectors

Get all supported integrations.

GET /v1/available-connectors

Query Parameters:

Response:

{
  "rows": [
    {
      "id": "conn_abc123",
      "name": "Gmail",
      "key": "gmail",
      "platform": "gmail",
      "platformVersion": "1.0.0",
      "status": "generally_available",
      "description": "Send and receive emails",
      "category": "Communication",
      "image": "https://assets.picaos.com/logos/gmail.svg",
      "tags": ["email", "google"],
      "oauth": true,
      "tools": 15,
      "version": "1.0.0",
      "active": true
    }
  ],
  "total": 200,
  "pages": 10,
  "page": 1
}

Example:

# Get all AuthKit-enabled connectors
curl "https://api.picaos.com/v1/available-connectors?authkit=true&limit=100" \
  -H "x-pica-secret: YOUR_API_KEY"

# Get CRM connectors
curl "https://api.picaos.com/v1/available-connectors?category=CRM" \
  -H "x-pica-secret: YOUR_API_KEY"

List Available Actions

Get actions for a specific platform.

GET /v1/available-actions/{platform}

Path Parameters:

Query Parameters:

Response:

{
  "rows": [
    {
      "title": "Send Email",
      "key": "gmail-send-email",
      "method": "POST",
      "platform": "gmail",
      "description": "Send an email message"
    },
    {
      "title": "List Labels",
      "key": "gmail-list-labels",
      "method": "GET",
      "platform": "gmail",
      "description": "Get all labels in the mailbox"
    }
  ],
  "total": 15,
  "pages": 1,
  "page": 1
}

Example:

# Get all Gmail actions
curl "https://api.picaos.com/v1/available-actions/gmail" \
  -H "x-pica-secret: YOUR_API_KEY"

# Get only POST actions for Slack
curl "https://api.picaos.com/v1/available-actions/slack?method=POST" \
  -H "x-pica-secret: YOUR_API_KEY"

Get Action Knowledge

Get detailed schema and parameters for a specific action.

GET /v1/actions/{actionId}/knowledge

Path Parameters:

Response:

{
  "action": {
    "id": "gmail-send-email",
    "title": "Send Email",
    "description": "Send an email message via Gmail",
    "method": "POST",
    "path": "/gmail/v1/users/me/messages/send"
  },
  "parameters": {
    "body": {
      "type": "object",
      "properties": {
        "to": {
          "type": "string",
          "description": "Recipient email address"
        },
        "subject": {
          "type": "string",
          "description": "Email subject line"
        },
        "body": {
          "type": "string",
          "description": "Email body content"
        }
      },
      "required": ["to", "subject", "body"]
    }
  },
  "examples": [
    {
      "description": "Send a simple email",
      "request": {
        "to": "recipient@example.com",
        "subject": "Hello",
        "body": "This is the email content."
      }
    }
  ]
}

Example:

curl "https://api.picaos.com/v1/actions/gmail-send-email/knowledge" \
  -H "x-pica-secret: YOUR_API_KEY"

Vault API (Connections)

List Connections

Get user’s connected integrations.

GET /v1/vault/connections

Query Parameters:

Response:

{
  "rows": [
    {
      "id": "conn_xyz789",
      "key": "live::gmail::default::abc123",
      "name": "My Gmail",
      "type": "api",
      "platform": "gmail",
      "environment": "live",
      "identity": "user_123",
      "identityType": "user",
      "state": "operational",
      "description": "Personal Gmail account",
      "tags": ["email", "personal"],
      "version": "1.0.0",
      "active": true,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 5,
  "pages": 1,
  "page": 1
}

Connection States:

Example:

# Get all connections for a user
curl "https://api.picaos.com/v1/vault/connections?identity=user_123&identityType=user" \
  -H "x-pica-secret: YOUR_API_KEY"

# Get Gmail connections only
curl "https://api.picaos.com/v1/vault/connections?platform=gmail" \
  -H "x-pica-secret: YOUR_API_KEY"

Get Connection

Get a specific connection by ID.

GET /v1/vault/connections/{connectionId}

Example:

curl "https://api.picaos.com/v1/vault/connections/conn_xyz789" \
  -H "x-pica-secret: YOUR_API_KEY"

Delete Connection

Remove a connection.

DELETE /v1/vault/connections/{connectionId}

Example:

curl -X DELETE "https://api.picaos.com/v1/vault/connections/conn_xyz789" \
  -H "x-pica-secret: YOUR_API_KEY"

Passthrough API

Execute actions directly on connected platforms. Responses match the underlying API’s format.

{METHOD} /v1/passthrough/{path}

Required Headers:

Optional Headers:

Example: Send Gmail

curl -X POST "https://api.picaos.com/v1/passthrough/gmail/v1/users/me/messages/send" \
  -H "x-pica-secret: YOUR_API_KEY" \
  -H "x-pica-connection-key: live::gmail::default::abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from Pica",
    "body": "This email was sent via the Pica Passthrough API."
  }'

Example: Post Slack Message

curl -X POST "https://api.picaos.com/v1/passthrough/slack/chat.postMessage" \
  -H "x-pica-secret: YOUR_API_KEY" \
  -H "x-pica-connection-key: live::slack::default::xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "#general",
    "text": "Hello from Pica!"
  }'

Example: Create HubSpot Contact

curl -X POST "https://api.picaos.com/v1/passthrough/hubspot/crm/v3/objects/contacts" \
  -H "x-pica-secret: YOUR_API_KEY" \
  -H "x-pica-connection-key: live::hubspot::default::def456" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "email": "newcontact@example.com",
      "firstname": "John",
      "lastname": "Doe"
    }
  }'

Example: Get Stripe Customers

curl "https://api.picaos.com/v1/passthrough/stripe/v1/customers?limit=10" \
  -H "x-pica-secret: YOUR_API_KEY" \
  -H "x-pica-connection-key: live::stripe::default::ghi789"

Common Patterns

Pagination

All list endpoints support pagination:

# First page, 50 results
curl "https://api.picaos.com/v1/available-connectors?limit=50&page=1" \
  -H "x-pica-secret: YOUR_API_KEY"

# Second page
curl "https://api.picaos.com/v1/available-connectors?limit=50&page=2" \
  -H "x-pica-secret: YOUR_API_KEY"

Multi-Tenant Filtering

Filter connections by identity:

# Get connections for specific user
curl "https://api.picaos.com/v1/vault/connections?identity=user_123&identityType=user" \
  -H "x-pica-secret: YOUR_API_KEY"

# Get connections for a team
curl "https://api.picaos.com/v1/vault/connections?identity=team_456&identityType=team" \
  -H "x-pica-secret: YOUR_API_KEY"

Error Handling

Pica returns standard HTTP status codes:

Error response format:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'platform' parameter is required"
  }
}

TypeScript Examples

List Connectors

async function getConnectors(category?: string) {
  const params = new URLSearchParams({ limit: "100" });
  if (category) params.set("category", category);

  const response = await fetch(
    `https://api.picaos.com/v1/available-connectors?${params}`,
    {
      headers: {
        "x-pica-secret": process.env.PICA_SECRET_KEY!,
      },
    }
  );

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

  return response.json();
}

Execute Passthrough Request

async function sendEmail(connectionKey: string, to: string, subject: string, body: string) {
  const response = await fetch(
    "https://api.picaos.com/v1/passthrough/gmail/v1/users/me/messages/send",
    {
      method: "POST",
      headers: {
        "x-pica-secret": process.env.PICA_SECRET_KEY!,
        "x-pica-connection-key": connectionKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ to, subject, body }),
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || "Failed to send email");
  }

  return response.json();
}

Get User Connections

async function getUserConnections(userId: string) {
  const params = new URLSearchParams({
    identity: userId,
    identityType: "user",
    active: "true",
  });

  const response = await fetch(
    `https://api.picaos.com/v1/vault/connections?${params}`,
    {
      headers: {
        "x-pica-secret": process.env.PICA_SECRET_KEY!,
      },
    }
  );

  return response.json();
}

Python Examples

List Connectors

import requests
import os

def get_connectors(category=None):
    params = {"limit": 100}
    if category:
        params["category"] = category

    response = requests.get(
        "https://api.picaos.com/v1/available-connectors",
        headers={"x-pica-secret": os.environ["PICA_SECRET_KEY"]},
        params=params,
    )
    response.raise_for_status()
    return response.json()

Execute Passthrough Request

def send_slack_message(connection_key, channel, text):
    response = requests.post(
        "https://api.picaos.com/v1/passthrough/slack/chat.postMessage",
        headers={
            "x-pica-secret": os.environ["PICA_SECRET_KEY"],
            "x-pica-connection-key": connection_key,
            "Content-Type": "application/json",
        },
        json={"channel": channel, "text": text},
    )
    response.raise_for_status()
    return response.json()

Troubleshooting

API Reference Summary

Links

• Dashboard: https://app.picaos.com
• API Keys: https://app.picaos.com/settings/api-keys
• Actions Browser: https://app.picaos.com/tools
• Documentation: https://docs.picaos.com