### Confirm setup intent

Source: https://docs.composio.dev/toolkits/stripe

Confirms a SetupIntent to complete customer payment method setup. Use when you need to finalize credential collection after creating a SetupIntent.

```APIDOC
## STRIPE_CONFIRM_SETUP_INTENT

### Description
Confirms a SetupIntent to complete customer payment method setup. Use when you need to finalize credential collection after creating a SetupIntent.

### Endpoint
STRIPE_CONFIRM_SETUP_INTENT

### Parameters
#### Request Body
- **return_url** (string) - Optional - URL to redirect customer after authentication. Required for redirect-based payment methods.
- **payment_method** (string) - Optional - ID of the PaymentMethod to attach to this SetupIntent.
- **use_stripe_sdk** (boolean) - Optional - Set to true when confirming server-side with Stripe.js or mobile SDKs.
- **setup_intent_id** (string) - Required - The unique identifier of the SetupIntent to confirm.
- **confirmation_token** (string) - Optional - ID of the ConfirmationToken used to confirm this SetupIntent.

### Response
#### Success Response (200)
- **data** (string) - Data from the action execution
- **error** (string) - Error if any occurred during the execution of the action
- **successful** (boolean) - Whether or not the action execution was successful or not
```

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

### STRIPE_GET_SETUP_ATTEMPTS

Source: https://docs.composio.dev/toolkits/stripe

Tool to list SetupAttempts associated with a SetupIntent. Use when you need to retrieve all setup attempts for a specific SetupIntent to understand the payment method setup process and any errors that occurred.

```APIDOC
## STRIPE_GET_SETUP_ATTEMPTS

### Description
Tool to list SetupAttempts associated with a SetupIntent. Use when you need to retrieve all setup attempts for a specific SetupIntent to understand the payment method setup process and any errors that occurred.

### Method Name
STRIPE_GET_SETUP_ATTEMPTS

### Parameters
- **limit** (integer) - Optional - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
- **created** (object) - Optional - Filter by creation date using Unix timestamps. Supported keys: 'gt' (greater than), 'gte' (greater than or equal), 'lt' (less than), 'lte' (less than or equal).
- **setup_intent** (string) - Required - Filter results to only SetupAttempts created by the specified SetupIntent ID. This parameter is required.
- **ending_before** (string) - Optional - A cursor for use in pagination. Object ID that defines your place in the list to fetch the previous page.
- **starting_after** (string) - Optional - A cursor for use in pagination. Object ID that defines your place in the list to fetch the next page.

### Output
- **data** (string) - Data from the action execution
- **error** (string) - Error if any occurred during the execution of the action
- **successful** (boolean) - Whether or not the action execution was successful or not
```

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

### Create MCP Server Configurations with `composio.experimental.mcp.create` in Python

Source: https://docs.composio.dev/reference/sdk-reference/python/mcp

Use these examples to create different MCP server configurations, including specifying toolkits with authentication, simple toolkit names, or allowing all tools from specified toolkits. The final example shows how to generate a server instance for a user.

```python
>>> # Using toolkit configuration objects with auth
>>> server = composio.experimental.mcp.create(
...     'personal-mcp-server',
...     toolkits=[
...         {
...             'toolkit': 'github',
...             'auth_config_id': 'ac_xyz',
...         },
...         {
...             'toolkit': 'slack',
...             'auth_config_id': 'ac_abc',
...         },
...     ],
...     allowed_tools=['GITHUB_CREATE_ISSUE', 'GITHUB_LIST_REPOS', 'SLACK_SEND_MESSAGE'],
...     manually_manage_connections=False
... )
>>>
>>> # Using simple toolkit names (most common usage)
>>> server = composio.experimental.mcp.create(
...     'simple-mcp-server',
...     toolkits=['composio_search', 'text_to_pdf'],
...     allowed_tools=['COMPOSIO_SEARCH_DUCK_DUCK_GO_SEARCH', 'TEXT_TO_PDF_CONVERT_TEXT_TO_PDF']
... )
>>>
>>> # Using all tools from toolkits (default behavior)
>>> server = composio.experimental.mcp.create(
...     'all-tools-server',
...     toolkits=['composio_search', 'text_to_pdf']
...     # allowed_tools=None means all tools from these toolkits
... )
>>>
>>> # Get server instance for a user
>>> mcp = server.generate('user_12345')
```

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

### Get deals timeline

Source: https://docs.composio.dev/toolkits/pipedrive

Returns opened and won deals in time-based groups according to a specified dealField, with examples of deals grouped by month over a 3-month period starting January 2012.

```APIDOC
## PIPEDRIVE_GET_DEALS_TIMELINE

### Description
Returns opened and won deals in time-based groups according to a specified dealField, with examples of deals grouped by month over a 3-month period starting January 2012.

### Request Body
- **amount** (integer) - Required - The number of given intervals, starting from `start_date`, to fetch. E.g. 3 (months).
- **user_id** (integer) - Optional - If supplied, only deals matching the given user will be returned
- **interval** (string ("day" | "week" | "month" | "quarter")) - Required - The type of the interval: `day`, `week` (7 days from `start_date`), `month` (full month from `start_date`), `quarter` (3 months from `start_date`).
- **field_key** (string) - Required - The date field key which deals will be retrieved from
- **filter_id** (integer) - Optional - If supplied, only deals matching the given filter will be returned
- **start_date** (string) - Required - The date when the first interval starts. Format: YYYY-MM-DD.
- **pipeline_id** (integer) - Optional - If supplied, only deals matching the given pipeline will be returned
- **exclude_deals** (integer) - Optional - Whether to exclude deals list (1) or not (0). Note that when deals are excluded, the timeline summary (counts and values) is still returned.
- **totals_convert_currency** (string) - Optional - The 3-letter currency code of any of the supported currencies. When supplied, `totals_converted` is returned per each interval which contains the currency-converted total amounts in the given currency. You may also set this parameter to `default_currency` in which case the user"s default currency is used.

### Response
#### Success Response (200)
- **data** (string) - Data from the action execution
- **error** (string) - Error if any occurred during the execution of the action
- **successful** (boolean) - Whether or not the action execution was successful or not
```

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

### Example - Get original tweets from Elon Musk since Sept 20, 2025

Source: https://docs.composio.dev/toolkits/twitter

Example query parameters for searching recent tweets, demonstrating how to filter by user, exclude retweets/replies, specify a start time, limit results, and request specific tweet fields and expansions.

```json
{ "query": "from:elonmusk -is:retweet -is:reply", "start_time": "2025-09-20T00:00:00Z", "max_results": 50, "tweet_fields": ["created_at","public_metrics","text"], "expansions": ["author_id","attachments.media_keys","referenced_tweets.id"] }
```

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

### Create Setup Intent

Source: https://docs.composio.dev/toolkits/stripe

Creates a SetupIntent object to collect payment method permissions for future payments. Use when setting up payment methods for subscriptions or saving cards for later use.

```APIDOC
## STRIPE_CREATE_SETUP_INTENT

### Description
Creates a SetupIntent object to collect payment method permissions for future payments. Use when setting up payment methods for subscriptions or saving cards for later use.

### Method
SDK Function Call

### Parameters
#### Input Parameters
- **usage** (string) - Optional - Indicates future payment method use. Values: off_session (default), on_session.
- **confirm** (boolean) - Optional - Set to true to immediately confirm this SetupIntent. Defaults to false. When confirming, you should provide return_url for card authentication.
- **customer** (string) - Optional - Customer ID this SetupIntent belongs to. Payment method will be attached to Customer on successful setup.
- **metadata** (object) - Optional - Key-value pairs for storing structured additional information.
- **return_url** (string) - Optional - URL to redirect customer after authentication/cancellation. Only with confirm=true.
- **single_use** (object) - Optional - Configuration for single-use mandates.
- **description** (string) - Optional - Arbitrary string attached to the object, useful for displaying to users.
- **mandate_data** (object) - Optional - Mandate creation details for the SetupIntent.
- **on_behalf_of** (string) - Optional - Stripe Account ID created for this SetupIntent.
- **attach_to_self** (boolean) - Optional - Attaches payment method to in-context Stripe Account for InboundTransfer/OutboundTransfers only. Cannot be true when setting up for a Customer.
- **payment_method** (string) - Optional - ID of payment method (PaymentMethod, Card, or saved Source) to attach.
- **use_stripe_sdk** (boolean) - Optional - Set true when confirming server-side with Stripe.js, iOS, or Android SDKs.
- **flow_directions** (array) - Optional - Indicates money movement direction. Values: inbound (pull funds from), outbound (send funds to).
- **customer_account** (string) - Optional - Account ID this SetupIntent belongs to. Payment method attaches to Account on successful setup.
- **confirmation_token** (string) - Optional - ID of ConfirmationToken used to confirm this SetupIntent.
- **payment_method_data** (object) - Optional - Creates PaymentMethod set as payment_method value. Must include 'type' field (e.g., 'card', 'sepa_debit').
- **payment_method_types** (array) - Optional - List of payment method types (e.g., 'card', 'sepa_debit') to accept. Stripe dynamically shows relevant methods if omitted and automatic_payment_methods is enabled.
- **payment_method_options** (object) - Optional - Payment method-specific configuration with subkeys for: acss_debit, bacs_debit, card, klarna, paypal, payto, sepa_debit, us_bank_account.
- **automatic_payment_methods** (object) - Optional - Configuration for automatic payment methods.
- **payment_method_configuration** (string) - Optional - ID of payment method configuration. Maximum length: 100 characters.
- **excluded_payment_method_types** (array) - Optional - Payment method types to exclude from this SetupIntent. Examples: 'card', 'sepa_debit', 'us_bank_account'.

### Response
#### Output Parameters
- **data** (string) - Required - Data from the action execution
- **error** (string) - Optional - Error if any occurred during the execution of the action
- **successful** (boolean) - Required - Whether or not the action execution was successful or not
```

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

### Example cURL Request

Source: https://docs.composio.dev/reference/api-reference/tools/getToolsByToolSlug

An example cURL command to retrieve tools by their slug using a GET request.

```bash
curl -X GET "https://backend.composio.dev/api/v3.1/tools/string" \
  -H "x-api-key: YOUR_API_KEY"
```

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

### Create ToolRouter Sessions with Detailed and Minimal Configurations (Python)

Source: https://docs.composio.dev/docs/changelog/2026/01/08

This example demonstrates creating a tool router session with detailed toolkit configurations, including specific authentication IDs. It also shows how to create a minimal session without specifying any toolkits.

```python
# Create session with detailed toolkit configurations
session = composio.experimental.tool_router.create_session(
    user_id='user_456',
    toolkits=[
        {
            'toolkit': 'github',
            'auth_config_id': 'ac_github_123'
        },
        {
            'toolkit': 'slack',
            'auth_config_id': 'ac_slack_456'
        }
    ],
    manually_manage_connections=True
)

# Minimal session (no specific toolkits)
session = composio.experimental.tool_router.create_session(
    user_id='user_789'
)
```

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

### Create Composio Session and Run Agent with OpenAI SDK

Source: https://docs.composio.dev/docs/providers/openai

Demonstrates how to initialize Composio with the OpenAI Agents Provider, create a user session, define an agent with tools, and execute a task.

```python
import asyncio
from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
from agents import Agent, Runner

composio = Composio(provider=OpenAIAgentsProvider())

# Create a session for your user
session = composio.create(user_id="user_123")
tools = session.tools()

agent = Agent(
    name="Email Agent",
    instructions="You are a helpful assistant.",
    tools=tools,
)

async def main():
    result = await Runner.run(
        starting_agent=agent,
        input="Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'",
    )
    print(result.final_output)

asyncio.run(main())
```

```typescript
import { Composio } from "@composio/core";
import { OpenAIAgentsProvider } from "@composio/openai-agents";
import { Agent, run } from "@openai/agents";

const composio = new Composio({
  provider: new OpenAIAgentsProvider(),
});

// Create a session for your user
const session = await composio.create("user_123");
const tools = await session.tools();

const agent = new Agent({
  name: "Email Agent",
  instructions: "You are a helpful assistant.",
  tools,
});

const result = await run(
  agent,
  "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'"
);

console.log(result.finalOutput);
```

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

### Get App Installation Functions

Source: https://docs.composio.dev/toolkits/contentful

Tool to get all functions for an app installation in a Contentful environment. Use when you need to retrieve the list of functions defined for an installed app in a specific space and environment.

```APIDOC
## CONTENTFUL_GET_SPACES_ENVS_APP_INSTALLATIONS_FUNCTIONS

### Description
Tool to get all functions for an app installation in a Contentful environment. Use when you need to retrieve the list of functions defined for an installed app in a specific space and environment.

### Operation
CONTENTFUL_GET_SPACES_ENVS_APP_INSTALLATIONS_FUNCTIONS

### Parameters
#### Input Parameters
- **space_id** (string) - Required - The ID of the Contentful space
- **environment_id** (string) - Required - The ID of the environment (e.g., 'master')
- **app_installation_id** (string) - Required - The ID of the installed app

### Response
#### Success Response
- **data** (string) - Data from the action execution
- **error** (string) - Error if any occurred during the execution of the action
- **successful** (boolean) - Whether or not the action execution was successful or not
```

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

### Preloading a Custom Tool

Source: https://docs.composio.dev/docs/extending-sessions/custom-tools-and-toolkits

Use `preload: true` (TypeScript) or `preload=True` (Python) when defining a custom tool to make it directly available in `session.tools()` without needing to be searched. This example defines a 'Get reply style guide' tool.

```typescript
import { Composio, experimental_createTool } from "@composio/core";
import { OpenAIAgentsProvider } from "@composio/openai-agents";
import { z } from "zod/v3";

const composio = new Composio({
  apiKey: "your_api_key",
  provider: new OpenAIAgentsProvider(),
});

const replyGuide = experimental_createTool("GET_REPLY_STYLE_GUIDE", {
  name: "Get reply style guide",
  description: "Return the team's email reply style guide",
  preload: true,
  inputParams: z.object({
    topic: z.string().describe("Email topic"),
  }),
  execute: async ({ topic }) => ({ topic, tone: "concise and helpful" }),
});

const session = await composio.create("user_1", {
  experimental: {
    customTools: [replyGuide],
  },
});

const tools = await session.tools();
console.log(tools.map((tool) => tool.name));
// LOCAL_GET_REPLY_STYLE_GUIDE
// COMPOSIO_SEARCH_TOOLS
// ... other default meta tools
```

```python
from pydantic import BaseModel, Field

from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider

composio = Composio(
    api_key="your_api_key",
    provider=OpenAIAgentsProvider(),
)

class ReplyGuideInput(BaseModel):
    topic: str = Field(description="Email topic")

@composio.experimental.tool(preload=True)
def get_reply_style_guide(input: ReplyGuideInput, ctx):
    """Return the team's email reply style guide."""
    return {"topic": input.topic, "tone": "concise and helpful"}

session = composio.create(
    user_id="user_1",
    experimental={
        "custom_tools": [get_reply_style_guide],
    },
)

tools = session.tools()
print([tool.name for tool in tools])
# LOCAL_GET_REPLY_STYLE_GUIDE
# COMPOSIO_SEARCH_TOOLS
# ... other default meta tools
```

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

### Example: Create a Tool Router Session (TypeScript)

Source: https://docs.composio.dev/reference/sdk-reference/typescript/sessions

Demonstrates how to create a new tool router session for a specific user, configuring toolkits, connection management, and experimental custom tools and toolkits.

```typescript
import { Composio } from '@composio/core';

const composio = new Composio();

const session = await composio.sessions.create('user_123', {
  toolkits: ['gmail'],
  manageConnections: true,
  experimental: {
    customTools: [myCustomTool],
    customToolkits: [myToolkit]
  }
});
```

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

### Example Response

Source: https://docs.composio.dev/reference/api-reference/tools/getToolsByToolSlug

An example of a successful response when retrieving tool details.

```json
{
  "slug": "string",
  "name": "string",
  "description": "string",
  "toolkit": {
    "slug": "string",
    "name": "string",
    "logo": "string"
  },
  "input_parameters": {
    "key": null
  },
  "no_auth": true,
  "available_versions": [
    "string"
  ],
  "version": "string",
  "output_parameters": {
    "key": null
  },
  "scopes": [
    "string"
  ],
  "scope_requirements": null,
  "tags": [
    "string"
  ],
  "human_description": "string",
  "is_deprecated": true,
  "deprecated": {
    "displayName": "string",
    "version": "string",
    "available_versions": [
      "string"
    ],
    "is_deprecated": true,
    "toolkit": {
      "logo": "string"
    }
  }
}
```