Invoke one Athlete Assistant 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 '
{
  "deal_id": 4821,
  "deal_type": "job"
}
'

import requests

url = "http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}"

payload = {
    "deal_id": 4821,
    "deal_type": "job"
}
headers = {
    "X-API-KEY": "<api-key>",
    "X-Mogl-Turn-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-API-KEY': '<api-key>',
    'X-Mogl-Turn-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({deal_id: 4821, deal_type: 'job'})
};

fetch('http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'deal_id' => 4821,
    'deal_type' => 'job'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>",
    "X-Mogl-Turn-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}"

	payload := strings.NewReader("{\n  \"deal_id\": 4821,\n  \"deal_type\": \"job\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("X-Mogl-Turn-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}")
  .header("X-API-KEY", "<api-key>")
  .header("X-Mogl-Turn-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"deal_id\": 4821,\n  \"deal_type\": \"job\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["X-Mogl-Turn-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deal_id\": 4821,\n  \"deal_type\": \"job\"\n}"

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "result": {
    "deal_id": 4821,
    "deal_type": "job",
    "title": "Summer Hydration Campaign",
    "brand": "Acme Athletics",
    "status": "In-Progress",
    "folder_id": 2051,
    "folder_action_state": "revision_requested",
    "applicable_deliverable_count": 1,
    "pending_upload_count": 0,
    "proof_of_work_required": true,
    "deliverables": [
      {
        "deliverable_id": 9121,
        "status": "Revision Requested",
        "lifecycle_state": "In-Progress",
        "file_action_state": "revision_requested",
        "applicable": true,
        "effective_guidance": "applicable",
        "effective_guidance_basis": "activity",
        "remaining_upload_slots": 4,
        "proof_of_work_required": true,
        "files": [
          {
            "file_id": 901,
            "deliverable_id": 9121,
            "status": "Revision Requested",
            "file_action_state": "revision_requested",
            "source_ids": [
              "job:4821",
              "deal_folder:2051",
              "deal_folder_file:901"
            ],
            "slot_number": 1,
            "file_name": "hydration-reel.mp4",
            "latest_brand_comment": {
              "comment_id": 78,
              "body": "Thanks — waiting on the tighter crop.",
              "author_role": "brand",
              "created_at_display": "Aug 21, 2026",
              "source_ids": [
                "job:4821",
                "deal_folder:2051",
                "deal_folder_file:901"
              ],
              "kind": "comment"
            },
            "active_revision_request": {
              "comment_id": 78,
              "body": "Thanks — waiting on the tighter crop.",
              "author_role": "brand",
              "created_at_display": "Aug 21, 2026",
              "source_ids": [
                "job:4821",
                "deal_folder:2051",
                "deal_folder_file:901"
              ],
              "kind": "comment"
            }
          }
        ],
        "source_ids": [
          "job:4821",
          "deal_folder:2051",
          "deal_folder_file:901"
        ],
        "name": "Product demo",
        "deliverable_type": "Instagram Reel",
        "description": "Film a 20-second product demo and upload a draft to the Deal Folder.",
        "catalog_guidance": "recommended",
        "completion_mode": "publish_social_content",
        "social_media": "Instagram",
        "helper_message": "Post the approved reel publicly.",
        "due_at_display": "Aug 28, 2026",
        "needs_completion_handoff": false
      }
    ],
    "source_ids": [
      "job:4821",
      "deal_folder:2051",
      "deal_folder_file:901"
    ],
    "athlete_relationship_state": "hired",
    "next_applicable_due_at_display": "Aug 28, 2026",
    "focused_file": {
      "file_id": 901,
      "deliverable_id": 9121,
      "status": "Revision Requested",
      "file_action_state": "revision_requested",
      "comments": [
        {
          "comment_id": 77,
          "body": "Please crop tighter on the product label.",
          "author_role": "brand",
          "created_at_display": "Aug 20, 2026",
          "kind": "comment",
          "source_ids": [
            "job:4821",
            "deal_folder:2051",
            "deal_folder_file:901"
          ]
        }
      ],
      "source_ids": [
        "job:4821",
        "deal_folder:2051",
        "deal_folder_file:901"
      ],
      "slot_number": 1,
      "file_name": "hydration-reel.mp4",
      "latest_brand_comment": {
        "comment_id": 78,
        "body": "Thanks — waiting on the tighter crop.",
        "author_role": "brand",
        "created_at_display": "Aug 21, 2026",
        "source_ids": [
          "job:4821",
          "deal_folder:2051",
          "deal_folder_file:901"
        ],
        "kind": "comment"
      },
      "active_revision_request": {
        "comment_id": 78,
        "body": "Thanks — waiting on the tighter crop.",
        "author_role": "brand",
        "created_at_display": "Aug 21, 2026",
        "source_ids": [
          "job:4821",
          "deal_folder:2051",
          "deal_folder_file:901"
        ],
        "kind": "comment"
      }
    }
  }
}

{
  "message": "Unauthenticated."
}

{
  "ok": false,
  "error": {
    "code": "fan_deal_not_allowed",
    "message": "Deal Folder facts are not available for fan deals.",
    "suggestion": "Use get_deal_folder only with a standard brand deal."
  }
}

{
  "ok": false,
  "error": {
    "code": "fan_deal_not_allowed",
    "message": "Deal Folder facts are not available for fan deals.",
    "suggestion": "Use get_deal_folder only with a standard brand deal."
  }
}

Invoke one Athlete Assistant tool

Server-to-server gateway used by mogl-ai-service. The path accepts exactly seven Laravel tools: get_portfolio, search_deals, get_deal, get_timeline, get_deal_folder, propose_brand_draft, and propose_support. search_kb is Python-local and is rejected here. Auth: both X-API-KEY and X-Mogl-Turn-Token are required; athlete identity is derived from the turn token and is never accepted in the body. HTTP 200 carries successful results and expected domain/tool errors (ok=false). HTTP 401 is reserved for missing or invalid credentials. HTTP 422 returns invalid_params. HTTP 503 returns unavailable. Unknown, deleted, unauthorized, and cross-athlete records use not_found. get_portfolio list rows with total_count at most three may include next_work_item for remaining Deal Folder or completion work; next_due_* remains the calendar deadline and may name a different deliverable. Compact lists of four or more omit next_work_item. Count and overview actions do not load folder work. get_deal_folder is a live read-only Deal Folder read for one host-bound standard job. Fan requests return fan_deal_not_allowed. Optional file_id must already appear as deal_folder_file: on a successful current-turn result. File states are awaiting_upload, awaiting_brand_review, revision_requested, approved, voided, and unknown; legacy submitted is rejected. Empty non-voided rows are awaiting_upload even when not applicable. approved requires a real approved file. unknown is non-actionable. remaining_upload_slots is capacity, not outstanding work. Ordinary latest_brand_comment is optional context. Formal revision reasons come only from active_revision_request. Focused comments include kind=comment|revision_request. File approval of an In-Progress deliverable continues through completion_mode and proof_of_work_required. Comments and files are bounded. The tool never marks comments read or changes folder state. get_deal.deal_folder is compatibility data only. Selected-deal focus (selected_deal_id) is host-derived on the AI loop result consumed by Laravel; it is not a field on this tool response and is not exposed on public athlete chat/history items.

POST

internal

ai-assistant

tools

{tool}

Invoke one Athlete Assistant 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 '
{
  "deal_id": 4821,
  "deal_type": "job"
}
'

import requests

url = "http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}"

payload = {
    "deal_id": 4821,
    "deal_type": "job"
}
headers = {
    "X-API-KEY": "<api-key>",
    "X-Mogl-Turn-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-API-KEY': '<api-key>',
    'X-Mogl-Turn-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({deal_id: 4821, deal_type: 'job'})
};

fetch('http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'deal_id' => 4821,
    'deal_type' => 'job'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>",
    "X-Mogl-Turn-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}"

	payload := strings.NewReader("{\n  \"deal_id\": 4821,\n  \"deal_type\": \"job\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("X-Mogl-Turn-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}")
  .header("X-API-KEY", "<api-key>")
  .header("X-Mogl-Turn-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"deal_id\": 4821,\n  \"deal_type\": \"job\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost/mogl/mogl-backend/api/internal/ai-assistant/tools/{tool}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["X-Mogl-Turn-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deal_id\": 4821,\n  \"deal_type\": \"job\"\n}"

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "result": {
    "deal_id": 4821,
    "deal_type": "job",
    "title": "Summer Hydration Campaign",
    "brand": "Acme Athletics",
    "status": "In-Progress",
    "folder_id": 2051,
    "folder_action_state": "revision_requested",
    "applicable_deliverable_count": 1,
    "pending_upload_count": 0,
    "proof_of_work_required": true,
    "deliverables": [
      {
        "deliverable_id": 9121,
        "status": "Revision Requested",
        "lifecycle_state": "In-Progress",
        "file_action_state": "revision_requested",
        "applicable": true,
        "effective_guidance": "applicable",
        "effective_guidance_basis": "activity",
        "remaining_upload_slots": 4,
        "proof_of_work_required": true,
        "files": [
          {
            "file_id": 901,
            "deliverable_id": 9121,
            "status": "Revision Requested",
            "file_action_state": "revision_requested",
            "source_ids": [
              "job:4821",
              "deal_folder:2051",
              "deal_folder_file:901"
            ],
            "slot_number": 1,
            "file_name": "hydration-reel.mp4",
            "latest_brand_comment": {
              "comment_id": 78,
              "body": "Thanks — waiting on the tighter crop.",
              "author_role": "brand",
              "created_at_display": "Aug 21, 2026",
              "source_ids": [
                "job:4821",
                "deal_folder:2051",
                "deal_folder_file:901"
              ],
              "kind": "comment"
            },
            "active_revision_request": {
              "comment_id": 78,
              "body": "Thanks — waiting on the tighter crop.",
              "author_role": "brand",
              "created_at_display": "Aug 21, 2026",
              "source_ids": [
                "job:4821",
                "deal_folder:2051",
                "deal_folder_file:901"
              ],
              "kind": "comment"
            }
          }
        ],
        "source_ids": [
          "job:4821",
          "deal_folder:2051",
          "deal_folder_file:901"
        ],
        "name": "Product demo",
        "deliverable_type": "Instagram Reel",
        "description": "Film a 20-second product demo and upload a draft to the Deal Folder.",
        "catalog_guidance": "recommended",
        "completion_mode": "publish_social_content",
        "social_media": "Instagram",
        "helper_message": "Post the approved reel publicly.",
        "due_at_display": "Aug 28, 2026",
        "needs_completion_handoff": false
      }
    ],
    "source_ids": [
      "job:4821",
      "deal_folder:2051",
      "deal_folder_file:901"
    ],
    "athlete_relationship_state": "hired",
    "next_applicable_due_at_display": "Aug 28, 2026",
    "focused_file": {
      "file_id": 901,
      "deliverable_id": 9121,
      "status": "Revision Requested",
      "file_action_state": "revision_requested",
      "comments": [
        {
          "comment_id": 77,
          "body": "Please crop tighter on the product label.",
          "author_role": "brand",
          "created_at_display": "Aug 20, 2026",
          "kind": "comment",
          "source_ids": [
            "job:4821",
            "deal_folder:2051",
            "deal_folder_file:901"
          ]
        }
      ],
      "source_ids": [
        "job:4821",
        "deal_folder:2051",
        "deal_folder_file:901"
      ],
      "slot_number": 1,
      "file_name": "hydration-reel.mp4",
      "latest_brand_comment": {
        "comment_id": 78,
        "body": "Thanks — waiting on the tighter crop.",
        "author_role": "brand",
        "created_at_display": "Aug 21, 2026",
        "source_ids": [
          "job:4821",
          "deal_folder:2051",
          "deal_folder_file:901"
        ],
        "kind": "comment"
      },
      "active_revision_request": {
        "comment_id": 78,
        "body": "Thanks — waiting on the tighter crop.",
        "author_role": "brand",
        "created_at_display": "Aug 21, 2026",
        "source_ids": [
          "job:4821",
          "deal_folder:2051",
          "deal_folder_file:901"
        ],
        "kind": "comment"
      }
    }
  }
}

{
  "message": "Unauthenticated."
}

{
  "ok": false,
  "error": {
    "code": "fan_deal_not_allowed",
    "message": "Deal Folder facts are not available for fan deals.",
    "suggestion": "Use get_deal_folder only with a standard brand deal."
  }
}

{
  "ok": false,
  "error": {
    "code": "fan_deal_not_allowed",
    "message": "Deal Folder facts are not available for fan deals.",
    "suggestion": "Use get_deal_folder only with a standard brand deal."
  }
}

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 AI turn token. The gateway derives athlete identity from this header; athlete IDs are never accepted in the tool body.

Headers

X-API-KEY

string

required

Server-to-server API key.

X-Mogl-Turn-Token

string

required

Signed short-lived turn token. Supplies athlete identity.

Path Parameters

tool

enum<string>

required

Laravel Athlete Assistant tool name. Seven values are accepted. Seven Laravel Athlete Assistant tools. search_kb is Python-local and is not accepted on this path.

Available options:

get_portfolio,

search_deals,

get_deal,

get_timeline,

get_deal_folder,

propose_brand_draft,

propose_support

Example:

"get_deal_folder"

Body

application/json

Closed per-tool input. Extra properties are rejected. get_deal_folder requires deal_id; deal_type defaults to job; file_id is optional and must already be trusted on the current turn.

deal_id

integer

required

Host-bound authorized standard job ID.

Required range: x >= 1

Example:

4821

deal_type

enum<string>

Available options:

job,

fan_req

Example:

"job"

file_id

integer | null

Optional focused file. Must already appear as deal_folder_file:{id} on a successful current-turn result.

Required range: x >= 1

Example:

901

Response

Successful tool result or expected domain error. get_deal_folder success is shown here; other tools use the same ok/result or ok/error envelope.

Option 1
Option 2

enum<boolean>

required

Available options:

true

Example:

true

result

object

required

Show child attributes

Core API

University API

Notifications API

Invoke one Athlete Assistant tool

Authorizations

Headers

Path Parameters

Body

Response