curl --request POST \
  --url http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-Mogl-Turn-Token: <api-key>' \
  --data '
{
  "segment": "awaiting_payment",
  "lifecycle": "all",
  "actions": [
    "count",
    "list"
  ],
  "sort": "default",
  "page_size": 3,
  "referenced_count": 3,
  "offset": 0
}
'

{
  "ok": true,
  "result": {
    "lifecycle_mode": "all",
    "requested_segment": "awaiting_payment",
    "requested_actions": [
      "list"
    ],
    "response_mode": "detail",
    "offset": 0,
    "requested_sort": "default",
    "page_size": 20,
    "ordering": "summary_priority_then_due_date_then_hired_at_then_job_id",
    "referenced_count": null,
    "summary_counts": {
      "all": 1,
      "active": 0,
      "in_progress": 0,
      "submitted": 0,
      "resubmit_needed": 0,
      "awaiting_payment": 1,
      "applied": 0,
      "invited": 0,
      "paid": 0,
      "voided": 0,
      "cancelled": 0,
      "rejected": 0
    },
    "deals": [
      {
        "job_id": 2833,
        "deal_type": "job",
        "title": "Summer Hydration Campaign",
        "brand_name": "Acme Athletics",
        "lifecycle_state": "current",
        "summary_state": "awaiting_payment",
        "next_due_at_display": "Aug 28, 2026",
        "next_due_deliverable": "Instagram Reel",
        "next_action": "Submit the Instagram Reel for brand review.",
        "compensation_summary": "$500.00",
        "source_ids": [
          "job:2833",
          "timeline:9121"
        ]
      }
    ],
    "total_count": 1,
    "returned_count": 1,
    "truncated": false,
    "count_mismatch": false,
    "continuation_cursor": null,
    "source_ids": [
      "portfolio:all:awaiting_payment",
      "job:2833",
      "timeline:9121"
    ]
  }
}

Invoke an athlete-scoped AI Assistant tool

Invokes one of six Laravel-owned tools. Athlete identity is derived only from the signed X-Mogl-Turn-Token and is never accepted in the request body. Both gateway credentials are required. A valid invocation returns HTTP 200 for either a successful tool result or an expected typed domain error. get_portfolio supports bounded overview, count, list, and guidance actions, default, recent-hire, or pending-invitation ordering, and page sizes from 1 to 20; omitted actions retain legacy list behavior, while positive offsets require list. The newest pending invitation uses segment=invited, lifecycle=all, actions=[list], sort=invited_at_desc, and page_size=1. Proposal tools are review-only. propose_brand_draft accepts only natural brand-facing text; known internal reason, telemetry, tool, or routing namespaces return the HTTP-200 invalid_params domain envelope without persistence. propose_support accepts the underlying issue rather than a contact instruction; its optional deal ID is host-bound and reauthorized, and Laravel renders trusted athlete, Brand, Deal, and Deal ID text.

POST

internal

ai-assistant

tools

{tool}

curl --request POST \
  --url http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-Mogl-Turn-Token: <api-key>' \
  --data '
{
  "segment": "awaiting_payment",
  "lifecycle": "all",
  "actions": [
    "count",
    "list"
  ],
  "sort": "default",
  "page_size": 3,
  "referenced_count": 3,
  "offset": 0
}
'

{
  "ok": true,
  "result": {
    "lifecycle_mode": "all",
    "requested_segment": "awaiting_payment",
    "requested_actions": [
      "list"
    ],
    "response_mode": "detail",
    "offset": 0,
    "requested_sort": "default",
    "page_size": 20,
    "ordering": "summary_priority_then_due_date_then_hired_at_then_job_id",
    "referenced_count": null,
    "summary_counts": {
      "all": 1,
      "active": 0,
      "in_progress": 0,
      "submitted": 0,
      "resubmit_needed": 0,
      "awaiting_payment": 1,
      "applied": 0,
      "invited": 0,
      "paid": 0,
      "voided": 0,
      "cancelled": 0,
      "rejected": 0
    },
    "deals": [
      {
        "job_id": 2833,
        "deal_type": "job",
        "title": "Summer Hydration Campaign",
        "brand_name": "Acme Athletics",
        "lifecycle_state": "current",
        "summary_state": "awaiting_payment",
        "next_due_at_display": "Aug 28, 2026",
        "next_due_deliverable": "Instagram Reel",
        "next_action": "Submit the Instagram Reel for brand review.",
        "compensation_summary": "$500.00",
        "source_ids": [
          "job:2833",
          "timeline:9121"
        ]
      }
    ],
    "total_count": 1,
    "returned_count": 1,
    "truncated": false,
    "count_mismatch": false,
    "continuation_cursor": null,
    "source_ids": [
      "portfolio:all:awaiting_payment",
      "job:2833",
      "timeline:9121"
    ]
  }
}

Authorizations

X-API-KEY

string

header

required

Server-to-Server API Key for internal/lambda/cron calls

X-Mogl-Turn-Token

string

header

required

Signed, short-lived Athlete Assistant turn token. Required together with X-API-KEY; athlete identity is derived from this token and never from tool input.

Path Parameters

tool

enum<string>

required

Closed Laravel tool name. search_kb is Python-local and is not available through this route.

Available options:

get_portfolio,

search_deals,

get_deal,

get_timeline,

propose_brand_draft,

propose_support

Example:

"get_portfolio"

Body

application/json

Input must match the schema for the selected path tool. Unknown properties are rejected; athlete identity is transport-owned.

Option 1
Option 2
Option 3
Option 4
Option 5

Normalized portfolio request. Omitted actions preserve the legacy effective default [list]. A positive offset is valid only when the effective action set includes list.

segment

enum<string>

default:all

Available options:

all,

active,

work_remaining,

in_progress,

submitted,

resubmit_needed,

awaiting_payment,

applied,

invited,

paid,

voided,

cancelled,

rejected

Example:

"work_remaining"

lifecycle

enum<string>

default:all

Available options:

all,

current,

historical

Example:

"all"

sort

enum<string>

default:default

Bounded row sort. hired_at_desc is reserved for explicit recent-hire intent with lifecycle=current, segment=all, and page_size=1. invited_at_desc is reserved for the newest pending invitation (segment=invited, lifecycle=all, page_size=1).

Available options:

default,

hired_at_desc,

invited_at_desc

Example:

"hired_at_desc"

page_size

integer

default:20

Maximum number of authorized rows returned for a list action.

Required range: 1 <= x <= 20

Example:

1

offset

integer

default:0

Backend-order offset. Positive offsets are continuation pages and require the effective list action.

Required range: 0 <= x <= 10000

Example:

0

actions

enum<string>[]

Requested deterministic output actions. The bounded loop sends these explicitly; omission retains legacy list behavior.

Required array length: 1 - 4 elements

Available options:

overview,

count,

list,

guidance

Example:

["overview", "count"]

referenced_count

integer

Optional trusted prior count used only for drift detection; it never limits current rows.

Required range: 0 <= x <= 10000

Example:

3

Response

Tool success or expected typed domain error. Inspect the ok discriminator.

enum<boolean>

required

Available options:

true

Example:

true

result

object

required

Strict normalized result. The expanded required metadata is an in-place v1 coordinated producer/consumer cutover.

Show child attributes

Core API

University API

Notifications API

Invoke an athlete-scoped AI Assistant tool

Authorizations

Path Parameters

Body

Response