Agents | Paid | Documentation

The Agent Object

1 class Agent
2   attr_accessor :id, :organization_id, :name, :description, :active,
3                 :agent_code, :external_id, :agent_attributes
4 end
5 
6 class AgentAttribute
7   attr_accessor :name, :active, :pricing
8 
9   class Pricing
10     attr_accessor :event_name, :charge_type, :pricing_model, :billing_frequency,
11                   :price_points, :taxable
12                   
13     class PricePoint
14       attr_accessor :unit_price, :min_quantity, :included_quantity, :tiers
15       
16       class Tier
17         attr_accessor :min_quantity, :max_quantity, :unit_price
18       end
19     end
20   end
21 end
22 
23 module ChargeType
24   ONE_TIME = "oneTime"
25   RECURRING = "recurring" 
26   USAGE = "usage"
27   SEAT_BASED = "seatBased"
28 end
29 
30 module PricingModelType
31   PER_UNIT = "PerUnit"
32   VOLUME_PRICING = "VolumePricing"
33   GRADUATED_PRICING = "GraduatedPricing"
34 end
35 
36 module BillingFrequency
37   MONTHLY = "Monthly"
38   QUARTERLY = "Quarterly"
39   SEMI_ANNUAL = "SemiAnnual"
40   ANNUAL = "Annual"
41 end
42 
43 module Currency
44   USD = "USD"
45   EUR = "EUR"
46   GBP = "GBP"
47 end

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the agent
`organization_id`	string	Organization ID the agent belongs to
`name`	string	The agent’s display name
`description`	string	Description of the agent
`active`	boolean	Whether the agent is active
`agent_code`	string	Optional code used to identify the agent
`external_id`	string	Optional external identifier for the agent
`agent_attributes`	array	Optional array of agent attributes

Agent Attribute

Attribute	Type	Description
`name`	string	Name of the attribute
`active`	boolean	Whether the attribute is active
`pricing`	object	Pricing configuration for the attribute
`pricing.event_name`	string	Optional name of the event
`pricing.charge_type`	string	Type of charge (‘usage’, ‘recurring’, ‘one_time’)
`pricing.pricing_model`	string	Type of pricing model (‘flat’, ‘tiered’, ‘volume’)
`pricing.billing_frequency`	string	Billing frequency (‘monthly’, ‘quarterly’, ‘yearly’)
`pricing.taxable`	boolean	Whether the charge is taxable
`pricing.price_points`	object	Price points for different currencies
`pricing.price_points[currency].unit_price`	number	Base unit price
`pricing.price_points[currency].min_quantity`	number	Minimum quantity
`pricing.price_points[currency].included_quantity`	number	Included quantity
`pricing.price_points[currency].tiers`	array	Optional pricing tiers

API Endpoints

Create an Agent

Creates a new agent with the given data.

SDK Functions

Ruby

1 require 'paid_ruby'
2 
3 # Initialize the client
4 api = Paid::Client.new(
5     token: "YOUR-API-KEY"
6 )
7 
8 # Create the agent
9 agent = api.agents.create(
10     name: "Customer Support AI Assistant",
11     description: "AI-powered customer support agent",
12     external_id: "ai_agent_123",
13 )

Returns

Returns the Agent object upon successful creation. It’s recommended to store the returned agent ID in your own system for future reference and operations.

1 {
2   id: 'uuid',
3   organization_id: 'uuid',
4   name: 'Customer Support AI Assistant',
5   description: 'AI-powered customer support agent',
6   active: false,
7   external_id: 'ai_agent_123',
8   agent_code: '',
9 }

Retrieve an Agent

Retrieves an agent by its internal or external ID.

SDK Functions

Ruby

1 # Retrieve agent using its internal ID 
2 agent = api.agents.get(agent_id: id)
3 
4 # Retrieve agent using its external ID 
5 agent = api.agents.get_by_external_id(external_id: id)

Returns

Returns the up-to-date Agent object for a valid identifier. Raises an error if get parameters are invalid (e.g. specifying an invalid internal agent ID)

1 {
2   id: 'uuid',
3   organization_id: 'uuid',
4   name: 'Customer Support AI Assistant',
5   description: 'AI-powered customer support agent',
6   active: false,
7   external_id: null,
8   agent_code: 'ai_agent_123',
9   agent_attributes: []
10 }

List all Agents

Retrieves all agents associated with your organization.

Ruby

1 # List all agents
2 agents = api.agents.list()

Returns

Returns the up-to-date list of Agent objects.

1 [
2 	{
3 	    id: 'uuid',
4 		organization_id: 'uuid',
5   		name: 'Customer Support AI Assistant.',
6   		description: 'AI-powered customer support agent',
7   		...
8 	},
9 	{
10 	    id: 'uuid',
11 		organization_id: 'uuid',
12   		name: 'AI Coding Assistant.',
13   		description: 'AI-powered coding agent',
14   		...
15 	}
16 ]

Update an Agent

Updates an agent’s information by its internal ID.

SDK Functions

Ruby

1 require 'paid_ruby'
2 
3 # Initialize the client
4 api = Paid::Client.new(
5     token: "YOUR-API-KEY"
6 )
7 
8 # Create agent attributes
9 agent_attributes = [
10     {
11         name: "monthly-messages",
12         active: true,
13         pricing: {
14             event_name: "subscription",
15             charge_type: Paid::ChargeType::RECURRING,
16             pricing_model: Paid::PricingModelType::GRADUATED_PRICING,
17             billing_frequency: Paid::BillingFrequency::MONTHLY,
18             taxable: true,
19             price_points: {
20                 "USD": {
21                     unit_price: 1.00,
22                     min_quantity: 0,
23                     included_quantity: 0,
24                     tiers: [
25                         {
26                             min_quantity: 0,
27                             max_quantity: 100,
28                             unit_price: 1.00
29                         },
30                         {
31                             min_quantity: 101,
32                             max_quantity: 1000,
33                             unit_price: 0.90
34                         }
35                     ]
36                 }
37             }
38         }
39     }
40 ]
41 
42 update_data = {
43     name: "Enhanced Customer Support AI",
44     description: "AI assistant with advanced features",
45     agent_code: "ENHANCED_SUPPORT_AI",
46     active: true,
47     agent_attributes: agent_attributes
48 }
49 
50 # Update agent by its internal ID
51 agent = api.agents.update(
52     agent_id: id,
53     request: update_data
54 )
55 
56 # Update agent by its external ID
57 agent = api.agents.update_by_external_id(
58     external_id: id,
59     request: update_data
60 )

Returns

Returns the updated Agent if the update succeeded. Raises an error if update parameters are invalid (e.g. specifying an invalid agent ID)

1 {
2   "id": "uuid",
3   "organization_id": "uuid",
4   "name": "Enhanced Customer Support AI",
5   "description": "AI assistant with advanced features",
6   "active": true,
7   "external_id": "ai_agent_123",
8   "agent_code": "ENHANCED_SUPPORT_AI",
9   "agent_attributes": [
10     {
11       "id": "uuid",
12       "name": "monthly-messages",
13       "active": true,
14       "pricing": {
15         "taxable": true,
16         "event_name": "subscription",
17         "charge_type": "recurring",
18         "price_points": {
19           "USD": {
20             "tiers": [
21               {
22                 "unit_price": 1,
23                 "max_quantity": 100,
24                 "min_quantity": 0
25               },
26               {
27                 "unit_price": 0.9,
28                 "max_quantity": 1000,
29                 "min_quantity": 101
30               }
31             ],
32             "unit_price": 1,
33             "min_quantity": 0,
34             "included_quantity": 0
35           }
36         },
37         "pricing_nodel": "GraduatedPricing",
38         "billing_frequency": "Monthly"
39       },
40       "agent_id": "uuid"
41     }
42   ]
43 }

Delete an Agent

Deletes an agent by its internal ID.

SDK Functions

ruby

1 # Delete agent by its internal ID
2 api.agents.delete(agent_id: id)
3 
4 # Delete agent by its external ID
5 api.agents.delete_by_external_id(external_id: id)

Returns

Returns the deleted Agent object on success. If the agent ID does not exist, this call raises an error.

1 {
2   "id": "uuid",
3   "organization_id": "uuid",
4   "name": "Enhanced Customer Support AI",
5   "description": "AI assistant with advanced features",
6   "active": true,
7   "external_id": "ai_agent_123",
8   "agent_code": "ENHANCED_SUPPORT_AI",
9   "agent_attributes": [
10     {
11       "id": "uuid",
12       "name": "monthly-messages",
13       "active": true,
14       "pricing": {
15         "taxable": true,
16         "event_name": "subscription",
17         "charge_type": "recurring",
18         "price_points": {
19           "USD": {
20             "tiers": [
21               {
22                 "unit_price": 1,
23                 "max_quantity": 100,
24                 "min_quantity": 0
25               },
26               {
27                 "unit_Price": 0.9,
28                 "max_quantity": 1000,
29                 "min_quantity": 101
30               }
31             ],
32             "unit_price": 1,
33             "min_quantity": 0,
34             "included_quantity": 0
35           }
36         },
37         "pricing_model": "GraduatedPricing",
38         "billing_frequency": "Monthly"
39       },
40       "agent_id": "uuid"
41     }
42   ]
43 }

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests:

2xx range indicates success
4xx range indicates an error that failed given the information provided
5xx range indicates an error with Paid’s servers

Error Response Format

1 {
2   "error": {
3     "message": "Error message",
4     "code": "ERROR_CODE",
5     "details": "Additional error details"
6   }
7 }

Common Error Codes

Code	Description
`AGENT_NOT_FOUND`	The specified agent does not exist
`INVALID_REQUEST`	The request was invalid
`UNAUTHORIZED`	The API key is invalid
`FORBIDDEN`	The API key doesn’t have permission to access the resource
`INTERNAL_SERVER_ERROR`	An error occurred on Paid’s servers