Today

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

Endpoints

POST
GET
GET
GET
GET
GET

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 highlights

The project's key metrics and up to 6 ranked items, each labeled risk or opportunity. Queries, rules and copy templates make every item; no AI is used. The highlights are computed in the background and stay fresh for 15 minutes per person, or 1 minute when a source failed. The call never waits: while they are computed, it returns computing with the last ready highlights of the day, so poll every 2 seconds until the status is ready or failed. 404 when the person does not have the new navigation. A scoped key needs query:read as well, because every highlight runs a query.

Required API key scopes

today:readquery:read

Response


Example request

GET /api/projects/:project_id/today/highlights
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/highlights/

Example response

Status 200
RESPONSE
{
  "status": "computing",
  "generated_at": "2019-08-24T14:15:22Z",
  "day": "2019-08-24",
  "refresh_at": "2019-08-24T14:15:22Z",
  "pulse": [
    {
      "key": "string",
      "name": "string",
      "value": 0.1,
      "unit": "events",
      "change_pct": 0,
      "series": [
        0.1
      ],
      "interval": "day",
      "url": "string",
      "value_format": {
        "format": "string",
        "prefix": "string",
        "postfix": "string",
        "decimal_places": 0
      },
      "period_starts": [
        "2019-08-24"
      ],
      "reason": "routine",
      "dashboard_name": "string",
      "dashboard_id": 0,
      "opened_days": 0,
      "last_opened": "2019-08-24",
      "previous_value": 0,
      "movers": [
        {
          "label": "string",
          "value": 0.1,
          "change_pct": 0
        }
      ]
    }
  ],
  "items": [
    {
      "key": "string",
      "label": "risk",
      "priority": "P1",
      "title": "string",
      "detail": "string",
      "url": "string",
      "series": [
        0.1
      ],
      "score": 0.1,
      "source": "string"
    }
  ],
  "pins": [
    {
      "key": "string",
      "status": "ready"
    }
  ]
}

Retrieve today pulse pins

The numbers the person keeps at the start of the key numbers on their home, in order. Suggestions fill the free places. 404 when the person does not have the new navigation.

Required API key scopes

today:read

Response


Example request

GET /api/projects/:project_id/today/pulse_pins
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/pulse_pins/

Example response

Status 200
RESPONSE
{
  "pins": [
    {
      "key": "string",
      "name": "string",
      "dashboard_id": 0
    }
  ]
}

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"
}