Daily briefing

A daily briefing is a short written summary of one user’s day: threads waiting on a reply, tasks due or overdue, today’s meetings, and changes Carom’s agents applied since the previous briefing. Carom writes it on request, from the records visible to that user, and each section links to the records it is based on.

Briefings belong to your key’s user and to their local calendar day. Generation runs in the background: Generate a briefing returns at once with a pending briefing, and you retrieve it until its status is ready or failed.

#The daily briefing object

Returned by both endpoints, wrapped in daily_briefing. content is filled in when generation finishes.

Attributes

idstring · uuid

Unique identifier for the briefing.
statusstring

Where generation stands. A briefing is pending until work starts on it and generating while it is being written.

pendinggeneratingreadyfailed
errorstring · nullable

A human-readable message saying why generation failed. Null unless status is failed.
contentobject · nullable

The briefing itself. Null until status is ready.
Show 6 child attributesHide child attributes
- headlinestring
  
  A title for the day, such as Reply Queue.
- summarystring
  
  One or two sentences on where to start.
- sectionsarray of objects
  
  The written part of the briefing, one section per topic.
  Show 5 child attributesHide child attributes
  - idstring · uuid
  - kindstring
    
    What the section is about: priority, the most important thing to act on; reply, threads waiting on a reply; task, tasks due or overdue; schedule, the day’s meetings; team_activity, task assignments, shares, and comments from teammates; watch, something to keep an eye on, such as a deal; quiet, nothing needed attention.
    
    priorityreplytaskscheduleteam_activitywatchquiet
  - headlinestring
  - detailstring
    
    Markdown text. Each record it mentions is a link of the form [label](ref:r1), where r1 is a key in refs.
  - refsobject
    
    The records detail links to, keyed by the handle used in the link. Each has a type in lowercase snake case, such as thread, calendar_event, task, or deal, an id, and a label.
- statsobject
  
  Counts computed directly from your records.
  Show 5 child attributesHide child attributes
  - meetings_todayinteger
    Calendar events today.
  - tasks_dueinteger
    Open tasks assigned to the user and due today.
  - tasks_overdueinteger
    Open tasks assigned to the user and past due.
  - new_threadsinteger
    Open threads with a message since the previous briefing, among threads received in the last 14 days.
  - agent_actionsinteger
    Proposals applied automatically since the previous briefing. Changes made through the chat assistant are not counted.
- fact_itemsarray of objects
  
  Today’s meetings, up to 6, then tasks due today or overdue, up to 5, most urgent first.
  Show 5 child attributesHide child attributes
  - idstring · uuid
  - typestring
    
    meetingtask_due
  - titlestring · nullable
    The meeting’s name or the task’s assignment.
  - detailstring
    The meeting’s start time in the user’s time zone, or when the task is due.
  - source_refsarray of objects
    The calendar event or task, as a type, id, and label.
- agent_actionsarray of proposals
  
  Up to 10 of the proposals counted in stats.agent_actions, as they stood when the briefing was written. Each lacks actions; retrieve the proposal to see what can still be done with it.
generated_atstring · date-time · nullable

When the briefing was requested.
regeneratable_atstring · date-time

The earliest time a new request will write a fresh briefing, one hour after generated_at. Before then, Generate a briefing returns this one.

The daily briefing object

{
  "id": "f2b4d6f8-0a2c-4e4a-8c6e-9a1c3e5a7c50",
  "status": "ready",
  "error": null,
  "content": {
    "headline": "Wildgrove Renewal Needs a Reply",
    "summary": "Start with Priya's renewal question, then prepare for the 2 PM review.",
    "sections": [
      {
        "id": "3c5e7a9c-1e3a-4c5e-9a7c-2e4a6c8e0a13",
        "kind": "reply",
        "headline": "Answer Priya on Renewal Terms",
        "detail": "Priya asked for the 2027 numbers in [Re: 2027 renewal terms](ref:r1) and is waiting on you.",
        "refs": {
          "r1": {
            "type": "thread",
            "id": "7a9c1e3f-5b7d-4f9a-a1c3-8e0b2d4f6a55",
            "label": "Re: 2027 renewal terms"
          }
        }
      }
    ],
    "stats": {
      "meetings_today": 1,
      "tasks_due": 1,
      "tasks_overdue": 1,
      "new_threads": 3,
      "agent_actions": 1
    },
    "fact_items": [
      {
        "id": "8e0a2c4e-6a8c-4e0a-b2c4-3e5a7c9e1a46",
        "type": "meeting",
        "title": "Wildgrove renewal review",
        "detail": "Friday, September 18, 2026 at 2:00 PM PDT",
        "source_refs": [
          {
            "type": "calendar_event",
            "id": "0b2d4f6a-8c0e-4a2c-b4e6-1d3f5a7c9e02",
            "label": "Wildgrove renewal review"
          }
        ]
      },
      {
        "id": "5a7c9e1a-3c5e-4a7c-8e1a-6c8e0a2c4e91",
        "type": "task_due",
        "title": "Send the Q4 renewal proposal",
        "detail": "Overdue — was due September 12, 2026",
        "source_refs": [
          {
            "type": "task",
            "id": "e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a01",
            "label": "Send the Q4 renewal proposal"
          }
        ]
      }
    ],
    "agent_actions": [
      {
        "id": "d8f0b2c4-6e8a-4b0c-8d2e-4a6c8e0b2d73",
        "agent": "auto_task",
        "action_type": "task.create",
        "status": "auto_applied",
        …
      }
    ]
  },
  "generated_at": "2026-09-18T15:02:11.482Z",
  "regeneratable_at": "2026-09-18T16:02:11.482Z"
}

get/daily_briefing Read key

#Retrieve today’s briefing

Returns the user’s most recent briefing from their current local day, whatever its status. Poll this after generating a briefing to learn when it is ready.

When no briefing exists for today, daily_briefing is null. Yesterday’s briefing stops being returned at the user’s local midnight.

Returns

The daily briefing object, wrapped in daily_briefing, or null.

get/daily_briefing

curl https://api.carom.io/daily_briefing \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "daily_briefing": {
    "id": "f2b4d6f8-0a2c-4e4a-8c6e-9a1c3e5a7c50",
    "status": "ready",
    "error": null,
    "content": {
      "headline": "Wildgrove Renewal Needs a Reply",
      "summary": "Start with Priya's renewal question, then prepare for the 2 PM review.",
      …
    },
    "generated_at": "2026-09-18T15:02:11.482Z",
    "regeneratable_at": "2026-09-18T16:02:11.482Z"
  }
}

post/daily_briefing Write key

#Generate a briefing

Asks Carom to write a briefing for the user’s day. The briefing covers what has happened since their previous ready briefing, or since the start of the day if this is the first.

Repeating the call is safe. If a briefing is already being generated, you get that one back with status 202. If a ready briefing is still before its regeneratable_at, you get it back with status 200 and nothing new is generated. Otherwise Carom starts a new briefing and returns it, pending, with status 202.

Returns

The daily briefing object, wrapped in daily_briefing: status 202 while it is pending or generating, 200 when an existing ready briefing is returned.

Errors

403permission_deniedThe account’s billing doesn’t allow a briefing to be written.
429rate_limitedThe user has started too many new briefings in the last hour. Returning an existing briefing doesn’t count. Wait the number of seconds in the Retry-After header.

post/daily_briefing

curl -X POST https://api.carom.io/daily_briefing \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response202

{
  "daily_briefing": {
    "id": "f2b4d6f8-0a2c-4e4a-8c6e-9a1c3e5a7c50",
    "status": "pending",
    "error": null,
    "content": null,
    "generated_at": "2026-09-18T15:02:11.482Z",
    "regeneratable_at": "2026-09-18T16:02:11.482Z"
  }
}