R1-Copywriting

The Copywriting Agent is used to write sales-oriented messages. You can use it to write sales emails. R1-Copywriting is trained on a large dataset of best-performing sales emails. When necessary, it can invoke the Research Agent to get the relevant information to write a message.

On this page, we'll dive into the R1-Copywriting endpoints you can use to trigger the Copywriting Agent programmatically.

POST/v1/agents/runs

Initiate a Copywriting run

This endpoint allows you to initiate a copywriting run of the R1-Copywriting agent.

Required attributes

Name
agent
Type
enum['r1-copywriting', 'r1-copywriting-light']
Description
The agent to run. Must be r1-copywriting or r1-copywriting-light. r1-copywriting uses the default research agent, which has access to a larger set of research sources, whereas r1-copywriting-light uses the light research agent to make it more affordable.
Name
lead
Type
Lead
Description
The lead to write a sales message for. See the Lead type for more information.

Optional attributes

Name
language
Type
LanguageCode
Description
The language to write the copy in. Defaults to en-US. See the LanguageCode type for a list of supported languages.
Name
max_research_steps
Type
integer
Description
In case you'd like to limit R1-Copywriting to a maximum amount of research steps, you can do so here. Defaults to 5.
Name
context
Type
string
Description
The context for the copywriting run. This is a free-form string that will be used to guide R1-Copywriting's copywriting and research. This can be anything, from the pain point you'd like to address, to the calendly link you'd like to use.
Name
user
Type
User
Description
The user that is initiating the copywriting run. Defaults to the user information that we have on file for the API key. Handy in case you're researching on behalf of another company. See the User type for more information.
Name
events
Type
[]Event
Description
Any previous events that have happened which are relevant for R1-Copywriting to use as context. See the Event type for more information.
Name
metadata
Type
Record<string, string>
Description
Free-format metadata that will be stored with the copywriting run. You can use this to store any information you want to associate with the research run. There can be up to 100 keys. The key must be less than 100 characters and the value must be less than 1000 characters.
Name
callback_url
Type
string
Description
The URL to call when the copywriting run is completed. The URL will receive a POST request with the copywriting run result (the same body as the response of the GET /v1/agents/runs/:run endpoint).
Name
use_memory
Type
boolean
Description
Whether the agent should remember and potentially use information gained from previous runs. Recommended in case you're running multiple agent runs on the same lead and you'd like to prevent duplicate research.

Returns

Name
id
Type
string
Description
The ID of the created copywriting run.

Request

POST

/v1/agents/runs

curl -X POST https://api.utopianlabs.ai/v1/agents/runs \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "r1-copywriting",
    "lead": {
      "company": {
        "website": "example.com",
        "name": "Example Corp"
      },
      "person": {
        "full_name": "John Smith",
        "job_title": "CEO"
      }
    },
    "max_research_steps": 5,
    "context": "We're looking to score a meeting with companies that have pain point X. Our calendly link is https://cal.com/utopianlabs/30min"
  }'

Response

{
  "id": "abc123"
}

GET/v1/agents/runs/:run

Retrieve Copywriting Run Status

This endpoint allows you to retrieve the status of a qualification run. In case the qualification run is completed, you will receive a list of research results.

Returns

Name
created_at
Type
number
Description
The timestamp of when the qualification run was created in milliseconds since the Unix epoch.
Name
id
Type
string
Description
The id of the copywriting run.
Name
status
Type
enum['queued', 'running', 'failed', 'completed']
Description
The status of the copywriting run.
Name
agent
Type
enum['r1-copywriting', 'r1-copywriting-light']
Description
The agent that was used to run the research.
Name
error
Type
string
Description
The error that occurred during the qualification run, if any.
Name
result
Type
CopywritingResult
Description
The result of the copywriting run, if any. See the CopywritingResult type for more information.
Name
metadata
Type
Optional<Record<string, string>>
Description
Free-format metadata that will be stored with the copywriting run. You can use this to store any information you want to associate with the copywriting run. There can be up to 100 keys. The key must be less than 100 characters and the value must be less than 1000 characters.

Request

GET

/v1/agents/runs/:run

curl https://api.utopianlabs.ai/v1/agents/runs/abc123 \
  -H "Authorization: Bearer {token}"

Response

{
  "created_at": 1736337711557,
  "id": "abc123",
  "agent": "r1-copywriting",
  "status": "completed",
  "result": {
    "research": {
      "conclusion": "An elaborate research report",
      "steps": [
        {
          "action": "I searched for customer reviews online",
          "outcome": "An elaboration on what R1 did and found"
        }
      ]
    },
    "message": {
      "subject": "Thought of you",
      "body": {
        "markdown": "Hi there,\n\nThis is a mind-blowing personalized message for you. Book a meeting with us [here](https://cal.com/utopianlabs/30min).",
        "html": "<p>Hi there,<br><br>This is a mind-blowing personalized message for you. Book a meeting with us <a href=\"https://cal.com/utopianlabs/30min\">here</a>.</p>"
      }
    }
  }
}