Today

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
POST
GET
POST
GET
GET
GET

Retrieve today briefing

Today's personal briefing: a short text about up to 5 items and the same items for the left bar. A new one is written every morning from 8:00 local time. Starts generating today's when there is none yet and returns it as 'collecting'. While a refresh is being written, the ready briefing is returned as 'writing', so it can stay on screen; poll again after a few seconds. 404 when the person gets no briefing: the flag is off, the organization has not approved AI data processing, or it is out of AI credits.

Required API key scopes

today:read

Query parameters

  • timezone
    string

Response


Example request

GET /api/projects/:project_id/today/briefing
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/today/briefing/

Example response

Status 200
RESPONSE
{
  "id": "string",
  "local_day": "2019-08-24",
  "headline": "string",
  "paragraphs": [
    [
      {
        "text": "string",
        "item_key": "string",
        "highlight": true
      }
    ]
  ],
  "items": [
    {
      "key": "string",
      "title": "string",
      "label": "string",
      "signal": "string",
      "url": "string",
      "rank": 0,
      "source_product": "string",
      "report": {
        "priority": "string",
        "summary": "string",
        "pull_request_state": "draft",
        "pull_request_url": "string",
        "signal_count": 0,
        "updated_at": "2019-08-24T14:15:22Z",
        "metrics": [
          {
            "metric_id": "string",
            "title": "string",
            "kind": "affected_users",
            "role": "primary",
            "value": 0.1,
            "series": [
              0.1
            ],
            "value_format": "number",
            "unit": "string",
            "query": null
          }
        ],
        "charts": [
          {
            "chart_id": "string",
            "title": "string",
            "query": null
          }
        ]
      },
      "group": "report",
      "source": "self_driving",
      "reason": "claimed_by_you",
      "state": "open"
    }
  ],
  "more_reports_count": 0,
  "open_reports_count": 0,
  "status": "collecting",
  "writer": "agent",
  "created_at": "2019-08-24T14:15:22Z",
  "ready_at": "2019-08-24T14:15:22Z"
}

Create today briefing refresh

Regenerate today's briefing. The ready briefing stays on screen until the new one is written.

Required API key scopes

today:write

Query parameters

  • timezone
    string

Response


Example request

POST /api/projects/:project_id/today/briefing/refresh
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/today/briefing/refresh/

Example response

Status 200
RESPONSE
{
  "id": "string",
  "local_day": "2019-08-24",
  "headline": "string",
  "paragraphs": [
    [
      {
        "text": "string",
        "item_key": "string",
        "highlight": true
      }
    ]
  ],
  "items": [
    {
      "key": "string",
      "title": "string",
      "label": "string",
      "signal": "string",
      "url": "string",
      "rank": 0,
      "source_product": "string",
      "report": {
        "priority": "string",
        "summary": "string",
        "pull_request_state": "draft",
        "pull_request_url": "string",
        "signal_count": 0,
        "updated_at": "2019-08-24T14:15:22Z",
        "metrics": [
          {
            "metric_id": "string",
            "title": "string",
            "kind": "affected_users",
            "role": "primary",
            "value": 0.1,
            "series": [
              0.1
            ],
            "value_format": "number",
            "unit": "string",
            "query": null
          }
        ],
        "charts": [
          {
            "chart_id": "string",
            "title": "string",
            "query": null
          }
        ]
      },
      "group": "report",
      "source": "self_driving",
      "reason": "claimed_by_you",
      "state": "open"
    }
  ],
  "more_reports_count": 0,
  "open_reports_count": 0,
  "status": "collecting",
  "writer": "agent",
  "created_at": "2019-08-24T14:15:22Z",
  "ready_at": "2019-08-24T14:15:22Z"
}

Retrieve today candidates

The items behind today's briefing, with the facts and the reason for each, without the written text.

Required API key scopes

today:read

Query parameters

  • timezone
    string

Response


Example request

GET /api/projects/:project_id/today/candidates
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/today/candidates/

Example response

Status 200
RESPONSE
{
  "local_day": "2019-08-24",
  "candidates": [
    {
      "key": "string",
      "title": "string",
      "url": "string",
      "rank": 0,
      "facts": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "group": "report",
      "source": "self_driving",
      "reason": "claimed_by_you"
    }
  ],
  "more_reports_count": 0
}

Create today excerpt choice

Asks the decision model which of several code excerpts shows what a finding describes. Returns null when it is unsure. 404 when the person may not use Jev.

Required API key scopes

today:read

Request parameters

  • finding
    string
  • excerpts
    array

Response


Example request

POST /api/projects/:project_id/today/excerpt_choice
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/today/excerpt_choice/\
	-d finding="string",\
	-d excerpts="array"

Example response

Status 200
RESPONSE
{
  "index": 0
}
Status 503 The decision model is unavailable.

Retrieve today reports figure marks

The numbers in the report's lead and impact sentence that a signal or the agent's research states, each with the sentence that states it. A number is marked only when the decision model is sure it is a measured result and that one source states the same result. 404 when the report is missing or the person may not use Jev.

Required API key scopes

today:readtask:read

Path parameters

  • report_id
    string

Response


Example request

GET /api/projects/:project_id/today/reports/:report_id/figure_marks
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/today/reports/:report_id/figure_marks/

Example response

Status 200
RESPONSE
{
  "marks": [
    {
      "text": "lead",
      "start": 0,
      "end": 0,
      "figure": "string",
      "quote": {
        "kind": "signal",
        "signal": {
          "signal_id": "string",
          "source_product": "string",
          "source_type": "string",
          "source_id": "string",
          "content": "string",
          "timestamp": "2019-08-24T14:15:22Z",
          "extra": {},
          "headline": "string",
          "lead": "string",
          "meta": "string",
          "cited": "code",
          "recording": {
            "session_id": "string",
            "start_at": "2019-08-24T14:15:22Z",
            "offset": "string",
            "seek_seconds": 0
          },
          "link": {
            "url": "string",
            "text": "string"
          },
          "preview": {
            "hint": "string",
            "code": [
              {
                "repo": "string",
                "path": "string"
              }
            ],
            "block": [
              {
                "text": "string",
                "quiet": true
              }
            ],
            "text": "string",
            "facts": [
              "string"
            ],
            "link": {
              "url": "string",
              "text": "string"
            },
            "link_label": "string"
          }
        },
        "at": "2019-08-24T14:15:22Z",
        "sentence": "string",
        "start": 0,
        "end": 0
      }
    }
  ]
}
Status 503 The decision model is unavailable.

Retrieve today reports key clauses

The clauses in the report page's lead, impact sentence and proposal that state the problem, its cause or the fix, each with sentences from the report that explain it. Only clauses the report explains further are returned, at most 2 across all texts. 404 when the report is missing or the person may not use Jev.

Required API key scopes

today:readtask:read

Path parameters

  • report_id
    string

Query parameters

  • include_impact
    boolean
    Default: true

Response


Example request

GET /api/projects/:project_id/today/reports/:report_id/key_clauses
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/today/reports/:report_id/key_clauses/

Example response

Status 200
RESPONSE
{
  "lead": [
    {
      "start": 0,
      "end": 0,
      "role": "problem",
      "expansion": [
        "string"
      ]
    }
  ],
  "impact": [
    {
      "start": 0,
      "end": 0,
      "role": "problem",
      "expansion": [
        "string"
      ]
    }
  ],
  "proposal": [
    {
      "start": 0,
      "end": 0,
      "role": "problem",
      "expansion": [
        "string"
      ]
    }
  ]
}
Status 503 The decision model is unavailable.

Retrieve today reports page

What the Today report page shows for a report: its lead, the proposal and the impact sentence cut to whole sentences, and the pull request it names. Sample report ids return the built-in sample reports. 404 when the report is missing or the person does not have the new navigation. 403 when the person may not read Inbox reports, and a scoped key needs task:read as well, because the page shows the report's signals.

Required API key scopes

today:readtask:read

Path parameters

  • report_id
    string

Response


Example request

GET /api/projects/:project_id/today/reports/:report_id/page
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/today/reports/:report_id/page/

Example response

Status 200
RESPONSE
{
  "lead": "string",
  "proposal": "string",
  "impact_sentence": "string",
  "named_pull_request": {
    "url": "string",
    "number": 0
  },
  "solution_names_pull_request": true,
  "evidence": [
    {
      "signal_id": "string",
      "source_product": "string",
      "source_type": "string",
      "source_id": "string",
      "content": "string",
      "timestamp": "2019-08-24T14:15:22Z",
      "extra": {},
      "headline": "string",
      "lead": "string",
      "meta": "string",
      "cited": "code",
      "recording": {
        "session_id": "string",
        "start_at": "2019-08-24T14:15:22Z",
        "offset": "string",
        "seek_seconds": 0
      },
      "link": {
        "url": "string",
        "text": "string"
      },
      "preview": {
        "hint": "string",
        "code": [
          {
            "repo": "string",
            "path": "string"
          }
        ],
        "block": [
          {
            "text": "string",
            "quiet": true
          }
        ],
        "text": "string",
        "facts": [
          "string"
        ],
        "link": {
          "url": "string",
          "text": "string"
        },
        "link_label": "string"
      }
    }
  ],
  "source_count": 0,
  "impact_numbers": [
    {
      "key": "tickets",
      "value": "string",
      "sentence": "string",
      "signal": {
        "signal_id": "string",
        "source_product": "string",
        "source_type": "string",
        "source_id": "string",
        "content": "string",
        "timestamp": "2019-08-24T14:15:22Z",
        "extra": {},
        "headline": "string",
        "lead": "string",
        "meta": "string",
        "cited": "code",
        "recording": {
          "session_id": "string",
          "start_at": "2019-08-24T14:15:22Z",
          "offset": "string",
          "seek_seconds": 0
        },
        "link": {
          "url": "string",
          "text": "string"
        },
        "preview": {
          "hint": "string",
          "code": [
            {
              "repo": "string",
              "path": "string"
            }
          ],
          "block": [
            {
              "text": "string",
              "quiet": true
            }
          ],
          "text": "string",
          "facts": [
            "string"
          ],
          "link": {
            "url": "string",
            "text": "string"
          },
          "link_label": "string"
        }
      },
      "values": [
        "string"
      ],
      "working": {
        "expression": "string",
        "result": "string"
      }
    }
  ],
  "last_seen": "2019-08-24T14:15:22Z"
}