Pine Voice API Reference

Authorization: Bearer <access_token>
X-Pine-User-Id: <user_id>
Content-Type: application/json

{
  "dialed_number": "+18005551234",
  "callee_name": "Internet Provider Support",
  "callee_context": "My internet service provider. Account #987654321. Current plan: 200 Mbps at $89.99/mo, subscribed for 3 years. Competitor offer: same speed at $49.99/mo from a local provider.",
  "call_objective": "Negotiate the monthly bill down from $89.99 to $60/mo or less",
  "detailed_instructions": "Target: $60/mo. Acceptable range: up to $65/mo. Mention the competitor offer as leverage. If they offer a promotional rate, ensure it lasts at least 12 months. Do NOT agree to change the plan tier or speed. If they cannot offer any discount, ask to speak with the retention department. As a last resort, request to cancel and see if a retention offer comes.",
  "caller": "negotiator",
  "voice": "male",
  "max_duration_minutes": 30
}

{
  "dialed_number": "+14155559876",
  "callee_name": "The Italian Place",
  "callee_context": "Italian restaurant on Main Street. Making a reservation for dinner.",
  "call_objective": "Make a dinner reservation for 4 people tonight at 7pm",
  "detailed_instructions": "If 7pm is not available, try 7:30 or 8pm. Prefer a booth if possible. Name for the reservation: Jane Doe.",
  "caller": "communicator",
  "voice": "female",
  "max_duration_minutes": 10
}

import requests
import time

# ---- Configuration ----
EMAIL = "[email protected]"
MY_PHONE = "+14155551234"

AUTH_API = "https://www.19pine.ai"
GATEWAY  = "https://agent3-api-gateway-staging.19pine.ai"

# ---- Step 1: Request verification code ----
print("Requesting verification code...")
resp = requests.post(f"{AUTH_API}/api/v2/auth/email/request", json={
    "email": EMAIL
})
resp.raise_for_status()
request_token = resp.json()["data"]["request_token"]
print("Check your email for the verification code.")

# ---- Step 2: Verify code and get credentials ----
code = input("Enter the code from your email: ")
resp = requests.post(f"{AUTH_API}/api/v2/auth/email/verify", json={
    "email": EMAIL,
    "request_token": request_token,
    "code": code
})
resp.raise_for_status()
creds = resp.json()["data"]
access_token = creds["access_token"]
user_id = creds["id"]
print(f"Authenticated! user_id={user_id}")

# ---- Step 3: Make a test call to yourself ----
headers = {
    "Authorization": f"Bearer {access_token}",
    "X-Pine-User-Id": user_id,
    "Content-Type": "application/json",
}

print(f"Initiating test call to {MY_PHONE}...")
resp = requests.post(f"{GATEWAY}/api/v2/voice/call", headers=headers, json={
    "dialed_number": MY_PHONE,
    "callee_name": "Myself",
    "callee_context": "This is a test call to verify my Pine Voice API integration is working.",
    "call_objective": "Tell the person that Pine Voice is set up and working correctly. Confirm the setup is complete and say goodbye.",
    "caller": "communicator",
    "voice": "female",
    "max_duration_minutes": 5,
})
resp.raise_for_status()
call_id = resp.json()["call_id"]
print(f"Call initiated! call_id={call_id}")
print("Your phone should ring shortly. Answer to hear the test message.")

# ---- Step 4: Poll for result ----
print("Polling for result...")
while True:
    time.sleep(10)
    resp = requests.get(
        f"{GATEWAY}/api/v2/voice/call/{call_id}",
        headers=headers,
    )
    result = resp.json()
    status = result["status"]
    elapsed = result.get("duration_seconds", 0)
    print(f"  Status: {status} ({elapsed}s elapsed)")

    if status in ("completed", "failed", "cancelled"):
        break

# ---- Step 5: Print results ----
print(f"\n--- Call {status} ---")
print(f"Duration: {result.get('duration_seconds', 0)}s")
print(f"Credits:  {result.get('credits_charged', 0)}")
print(f"\nSummary:\n  {result.get('summary', 'N/A')}")
print(f"\nTranscript:")
for entry in result.get("transcript", []):
    print(f"  [{entry['speaker']}] {entry['text']}")

# Step 1: Request verification code
curl -s -X POST https://www.19pine.ai/api/v2/auth/email/request \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
# Save the request_token from the response

# Step 2: Verify code (replace REQUEST_TOKEN and CODE)
curl -s -X POST https://www.19pine.ai/api/v2/auth/email/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "request_token": "REQUEST_TOKEN", "code": "CODE"}'
# Response: {"status":"success","data":{"id":"...","access_token":"..."}}
# Save data.id as YOUR_USER_ID and data.access_token as YOUR_ACCESS_TOKEN

# Step 3: Make a test call to yourself
curl -s -X POST https://agent3-api-gateway-staging.19pine.ai/api/v2/voice/call \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Pine-User-Id: YOUR_USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "dialed_number": "+14155551234",
    "callee_name": "Myself",
    "callee_context": "This is a test call to verify my Pine Voice API integration is working.",
    "call_objective": "Tell the person that Pine Voice is set up and working correctly. Confirm the setup is complete and say goodbye.",
    "caller": "communicator",
    "voice": "female",
    "max_duration_minutes": 5
  }'
# Save the call_id from the response

# Step 4: Poll for result (repeat until status is terminal)
curl -s https://agent3-api-gateway-staging.19pine.ai/api/v2/voice/call/CALL_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Pine-User-Id: YOUR_USER_ID"

from pine_voice import PineVoice

# Authenticate (one-time setup)
request_token = PineVoice.auth.request_code("[email protected]")
code = input("Enter the code from your email: ")
credentials = PineVoice.auth.verify_code("[email protected]", request_token, code)

# Create client and make a call
client = PineVoice(
    access_token=credentials.access_token,
    user_id=credentials.user_id,
)
result = client.calls.create_and_wait(
    to="+14155551234",
    name="Dr. Smith Office",
    context="Local dentist office. Open Mon-Fri 9am-5pm.",
    objective="Schedule a dental cleaning for next Tuesday afternoon",
)
print(result.status, result.transcript)

import { PineVoice } from "pine-voice";

// Authenticate (one-time setup)
const { requestToken } = await PineVoice.auth.requestCode("[email protected]");
const { accessToken, userId } = await PineVoice.auth.verifyCode(
  "[email protected]", requestToken, "1234"
);

// Create client and make a call
const client = new PineVoice({ accessToken, userId });
const result = await client.calls.createAndWait({
  to: "+14155551234",
  name: "Dr. Smith Office",
  context: "Local dentist office. Open Mon-Fri 9am-5pm.",
  objective: "Schedule a dental cleaning for next Tuesday afternoon",
});
console.log(result.status, result.transcript);

pip install pine-voice

# Option 1: Explicit credentials
client = PineVoice(access_token="...", user_id="...")

# Option 2: From environment variables
# export PINE_ACCESS_TOKEN=... PINE_USER_ID=...
client = PineVoice()

# Use as a context manager to auto-close
with PineVoice() as client:
    result = client.calls.create_and_wait(...)

import time
from pine_voice import PineVoice, CallResult

client = PineVoice()
initiated = client.calls.create(
    to="+14155551234",
    name="Dr. Smith Office",
    context="Local dentist office",
    objective="Schedule a cleaning",
)
print(f"Call started: {initiated.call_id}")

# Poll until complete
while True:
    time.sleep(10)
    result = client.calls.get(initiated.call_id)
    if result.status in ("completed", "failed", "cancelled"):
        break
    print(f"  Still in progress... {result.duration_seconds}s")

if isinstance(result, CallResult):
    for entry in result.transcript:
        print(f"[{entry.speaker}] {entry.text}")

result = client.calls.create_and_wait(
    to="+14155551234",
    name="Dr. Smith Office",
    context="Local dentist office. I'm Jane Doe, existing patient.",
    objective="Schedule a dental cleaning for next Tuesday afternoon",
    instructions="If Tuesday is unavailable, try Wednesday or Thursday.",
    enable_summary=True,
)

print(f"Status: {result.status}")
print(f"Duration: {result.duration_seconds}s")
print(f"Credits: {result.credits_charged}")
print(f"Summary: {result.summary}")
for entry in result.transcript:
    print(f"[{entry.speaker}] {entry.text}")

import asyncio
from pine_voice import AsyncPineVoice

async def main():
    async with AsyncPineVoice() as client:
        result = await client.calls.create_and_wait(
            to="+14155551234",
            name="Dr. Smith Office",
            context="Local dentist office",
            objective="Schedule a cleaning",
        )
        print(result.transcript)

asyncio.run(main())

from pine_voice import PineVoice, AuthError, CallError, RateLimitError

try:
    result = client.calls.create_and_wait(...)
except AuthError as e:
    print(f"Auth failed: {e.code} — {e.message}")
except RateLimitError:
    print("Too many concurrent calls, try again later")
except CallError as e:
    print(f"Call error: {e.code} — {e.message}")

npm install pine-voice

import { PineVoice } from "pine-voice";

// Option 1: Explicit credentials
const client = new PineVoice({ accessToken: "...", userId: "..." });

// Option 2: From environment variables
// PINE_ACCESS_TOKEN=... PINE_USER_ID=...
const client = new PineVoice();

const { callId } = await client.calls.create({
  to: "+14155551234",
  name: "Dr. Smith Office",
  context: "Local dentist office",
  objective: "Schedule a cleaning",
});

// Poll until complete
while (true) {
  await new Promise(r => setTimeout(r, 10000));
  const result = await client.calls.get(callId);
  if (["completed", "failed", "cancelled"].includes(result.status)) {
    console.log(result);
    break;
  }
}

const result = await client.calls.createAndWait(
  {
    to: "+14155551234",
    name: "Dr. Smith Office",
    context: "Local dentist office. I'm Jane Doe, existing patient.",
    objective: "Schedule a dental cleaning for next Tuesday afternoon",
    enableSummary: true,
  },
  {
    // Optional: abort after 5 minutes
    signal: AbortSignal.timeout(300_000),
  }
);

console.log(result.status);        // "completed"
console.log(result.durationSeconds); // 45
console.log(result.creditsCharged);  // 70
console.log(result.summary);        // "Scheduled cleaning for Tuesday 2pm"
console.log(result.transcript);     // [{ speaker, text }, ...]

import { PineVoice, AuthError, CallError, RateLimitError } from "pine-voice";

try {
  const result = await client.calls.createAndWait({...});
} catch (err) {
  if (err instanceof AuthError) {
    console.error(`Auth failed: ${err.code} — ${err.message}`);
  } else if (err instanceof RateLimitError) {
    console.error("Too many concurrent calls, try again later");
  } else if (err instanceof CallError) {
    console.error(`Call error: ${err.code} — ${err.message}`);
  }
}

[
  { "speaker": "agent", "text": "Hello, I'm calling to..." },
  { "speaker": "user",  "text": "Hi, how can I help?" }
]

{
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of the error."
  }
}