> ## Documentation Index > Fetch the complete documentation index at: https://developer.mogl.online/llms.txt > Use this file to discover all available pages before exploring further. # 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:{id} 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. ## OpenAPI ````yaml /storage/api-docs/api-docs.json post /internal/ai-assistant/tools/{tool} openapi: 3.0.0 info: title: MOGL Core API description: >- MOGL Platform Core API — powering athlete NIL deals, brand partnerships, agent management, payments, messaging, and more. * * ## Authentication * - **JWT Bearer Token**: Most endpoints require a Bearer token obtained via `/api/login`. * - **Server-to-Server API Key**: Internal/lambda/cron endpoints use an `X-API-KEY` header. * * ## Rate Limiting * - Registration & login endpoints: 4–15 requests per minute * - Public/influencer endpoints: 200 requests per minute * - Authenticated endpoints: standard Laravel throttle version: 1.0.0 servers: - url: http://localhost/mogl/mogl-backend/api description: Local - url: https://dev-api.mogl.online/api description: Dev - url: https://staging-api.mogl.online/api description: Staging - url: https://api.mogl.online/api description: Production security: - bearerAuth: [] tags: - name: Authentication description: Login, registration, password reset - name: User Registration - Common description: Common user registration & email check - name: User Registration - Athlete description: Athlete registration & onboarding steps - name: User Registration - Partner description: Partner/Brand registration & onboarding steps - name: User Registration - Agent description: Agent registration & onboarding steps - name: User Registration - Fan description: Fan registration & onboarding steps - name: User Profile description: User profile management, settings, social media - name: Athlete description: 'Athlete-specific endpoints: search, details, availability' - name: Athlete - Availability Confirmation description: Post-hiring availability confirmation workflow - name: Athlete - NIL Feed description: Athlete NIL feed and partner search - name: Athlete - AI Assistant description: >- AI-powered job assistant for athletes — chat, conversation history, read state, and clarification drafts - name: Athlete - AI Waitlist description: AI Athlete Assistant waitlist status, social proof, and joining - name: Partner description: Partner/Brand-specific endpoints - name: Partner - External Job description: External job link & applicant management - name: Partner - Deliverable Report description: Deliverable detail reports for brands - name: Partner - Screening Questions description: Screening question reports - name: Partner - Contract Management description: Brand contract management with athletes - name: Partner - Content Library description: Brand content library for deliverable assets - name: Agent description: Agent profile, athlete management, contracts - name: Agent - Athletes description: Agent-athlete relationship management - name: Agent - Stripe description: Agent payment methods & billing via Stripe - name: Agent - Contracts description: Agent athlete contract management - name: Agent - Availability Confirmation description: Agent managing athlete job availability - name: Jobs description: Job/deal CRUD, search, invitations, hiring, deliverables - name: Deals description: Deal listing, my deals, bulk operations - name: Deal Folder description: >- Deal folder file workflow — uploads, replacements, approvals, revisions, comments. Accessible by athlete, partner/brand, agent, and iOS clients (per-action authorisation enforced server-side). - name: Deal Folder iOS API description: >- iOS-only direct-to-S3 multipart upload endpoints for deal folder files (initiate/complete for new uploads and replacements). Web clients should use the standard `Deal Folder` upload/replace endpoints instead. - name: Chat description: Messaging, chat contacts, notifications - name: Notifications description: Notification preferences, in-app notifications - name: Payments description: Stripe payments, payment history, cards, bulk pay - name: Subscription description: Brand subscription plans & management - name: Public Pages description: Public content endpoints (no auth required) - name: Public - Influencer/SEO description: Public influencer discovery, sitemaps, directories - name: Services description: Athlete service marketplace - name: iOS Device description: iOS device tokens, live activities - name: Onboarding Tutorial description: Onboarding tutorial progress - name: MOGL Rosters description: Roster management & display - name: Internal / Cron description: Server-to-server and cron job endpoints - name: Internal / AI Assistant Tools description: >- Server-to-server Athlete Assistant tool gateway used by mogl-ai-service. Seven Laravel tools share POST /internal/ai-assistant/tools/{tool}. search_kb is Python-local and is not in this path enum. - name: Affiliate description: Athlete affiliate links & tracking paths: /internal/ai-assistant/tools/{tool}: post: tags: - Internal / AI Assistant Tools summary: Invoke one Athlete Assistant tool description: >- 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:{id} 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. operationId: invokeInternalAiAssistantTool parameters: - name: tool in: path description: Laravel Athlete Assistant tool name. Seven values are accepted. required: true schema: $ref: '#/components/schemas/InternalAiAssistantToolName' - name: X-API-KEY in: header description: Server-to-server API key. required: true schema: type: string - name: X-Mogl-Turn-Token in: header description: Signed short-lived turn token. Supplies athlete identity. required: true schema: type: string requestBody: description: >- 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. required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/GetDealFolderInput' - $ref: '#/components/schemas/InternalAiAssistantGetDealInput' - $ref: '#/components/schemas/InternalAiAssistantSearchDealsInput' - $ref: '#/components/schemas/InternalAiAssistantGetPortfolioInput' - $ref: >- #/components/schemas/InternalAiAssistantProposeBrandDraftInput - $ref: '#/components/schemas/InternalAiAssistantProposeSupportInput' example: deal_id: 4821 deal_type: job responses: '200': description: >- 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. content: application/json: schema: oneOf: - $ref: '#/components/schemas/GetDealFolderSuccessEnvelope' - $ref: '#/components/schemas/InternalAiAssistantToolErrorEnvelope' '401': description: Missing or invalid gateway credentials. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '422': description: Malformed tool name or request input. content: application/json: schema: $ref: '#/components/schemas/InternalAiAssistantToolErrorEnvelope' '503': description: Unexpected gateway failure. content: application/json: schema: $ref: '#/components/schemas/InternalAiAssistantToolErrorEnvelope' security: - serverToServerApiKey: [] moglTurnToken: [] components: schemas: InternalAiAssistantToolName: description: >- Seven Laravel Athlete Assistant tools. search_kb is Python-local and is not accepted on this path. type: string enum: - get_portfolio - search_deals - get_deal - get_timeline - get_deal_folder - propose_brand_draft - propose_support example: get_deal_folder GetDealFolderInput: required: - deal_id properties: deal_id: description: Host-bound authorized standard job ID. type: integer minimum: 1 example: 4821 deal_type: $ref: '#/components/schemas/InternalAiAssistantDealType' file_id: description: >- Optional focused file. Must already appear as deal_folder_file:{id} on a successful current-turn result. type: integer minimum: 1 example: 901 nullable: true type: object additionalProperties: false InternalAiAssistantGetDealInput: required: - deal_id properties: deal_id: type: integer minimum: 1 example: 4821 deal_type: $ref: '#/components/schemas/InternalAiAssistantDealType' type: object additionalProperties: false InternalAiAssistantSearchDealsInput: required: - query properties: query: type: string maxLength: 200 minLength: 1 example: hydration type: object additionalProperties: false InternalAiAssistantGetPortfolioInput: properties: segment: type: string enum: - all - active - work_remaining - in_progress - submitted - resubmit_needed - awaiting_payment - applied - invited - paid - voided - cancelled - rejected example: all lifecycle: type: string enum: - all - current - historical example: all sort: type: string enum: - default - hired_at_desc - invited_at_desc example: default page_size: type: integer maximum: 20 minimum: 1 example: 20 offset: type: integer maximum: 10000 minimum: 0 example: 0 actions: type: array items: type: string enum: - overview - count - list - guidance maxItems: 4 minItems: 1 uniqueItems: true referenced_count: type: integer minimum: 0 example: null nullable: true type: object additionalProperties: false InternalAiAssistantProposeBrandDraftInput: required: - deal_id - draft_text properties: deal_id: type: integer minimum: 1 example: 4821 draft_text: type: string maxLength: 1000 minLength: 1 example: Can I wear sandals in the video? type: object additionalProperties: false InternalAiAssistantProposeSupportInput: required: - summary properties: summary: type: string maxLength: 500 minLength: 1 example: The athlete needs help resolving a payout issue. deal_id: type: integer minimum: 1 example: 4821 nullable: true type: object additionalProperties: false GetDealFolderSuccessEnvelope: required: - ok - result properties: ok: type: boolean enum: - true example: true result: $ref: '#/components/schemas/GetDealFolderResult' type: object additionalProperties: false InternalAiAssistantToolErrorEnvelope: required: - ok - error properties: ok: type: boolean enum: - false example: false error: $ref: '#/components/schemas/InternalAiAssistantToolError' type: object additionalProperties: false UnauthorizedResponse: properties: message: type: string example: Unauthenticated. type: object InternalAiAssistantDealType: type: string enum: - job - fan_req example: job GetDealFolderResult: required: - deal_id - deal_type - title - brand - status - folder_id - folder_action_state - applicable_deliverable_count - pending_upload_count - proof_of_work_required - deliverables - source_ids properties: deal_id: type: integer minimum: 1 example: 4821 deal_type: $ref: '#/components/schemas/InternalAiAssistantDealType' title: type: string maxLength: 200 minLength: 1 example: Summer Hydration Campaign brand: type: string maxLength: 200 minLength: 1 example: Acme Athletics status: type: string maxLength: 80 minLength: 1 example: In-Progress athlete_relationship_state: $ref: '#/components/schemas/InternalAiAssistantAthleteRelationshipState' folder_id: type: integer minimum: 1 example: 2051 folder_action_state: $ref: '#/components/schemas/GetDealFolderFileActionState' applicable_deliverable_count: type: integer maximum: 20 minimum: 0 example: 1 pending_upload_count: type: integer maximum: 20 minimum: 0 example: 0 next_applicable_due_at_display: type: string maxLength: 120 minLength: 1 example: Aug 28, 2026 proof_of_work_required: type: boolean example: true deliverables: type: array items: $ref: '#/components/schemas/GetDealFolderDeliverable' maxItems: 20 focused_file: $ref: '#/components/schemas/GetDealFolderFocusedFile' source_ids: $ref: '#/components/schemas/InternalAiAssistantSourceIds' type: object additionalProperties: false InternalAiAssistantToolError: required: - code - message - suggestion properties: code: description: >- Closed schemas for POST /internal/ai-assistant/tools/{tool}. Canonical JSON Schema copies live in contracts/athlete-assistant-tools/v1/. get_deal_folder is the live Deal Folder authority. get_deal.deal_folder is compatibility data only and is not documented here as a lifecycle source. type: string enum: - not_found - invalid_params - fan_deal_not_allowed - draft_not_allowed - unavailable - budget_exceeded example: fan_deal_not_allowed message: type: string maxLength: 500 minLength: 1 example: Deal Folder facts are not available for fan deals. suggestion: type: string maxLength: 500 minLength: 1 example: Use get_deal_folder only with a standard brand deal. type: object additionalProperties: false InternalAiAssistantAthleteRelationshipState: description: Trusted mapping application status. Invited is not applied. type: string enum: - hired - applied - invited - rejected - cancelled example: hired GetDealFolderFileActionState: description: >- Closed physical file-review states. Legacy submitted is rejected. Empty non-voided rows are awaiting_upload even when not applicable. approved requires a real FILE_APPROVED file. unknown is an unrecognized persisted status and is non-actionable. awaiting_brand_review means the file is with the brand and no required file action exists unless a formal revision is requested. type: string enum: - awaiting_upload - awaiting_brand_review - revision_requested - approved - voided - unknown example: revision_requested GetDealFolderDeliverable: required: - deliverable_id - status - lifecycle_state - file_action_state - applicable - effective_guidance - effective_guidance_basis - remaining_upload_slots - proof_of_work_required - files - source_ids properties: deliverable_id: type: integer minimum: 1 example: 9121 name: type: string maxLength: 300 minLength: 1 example: Product demo deliverable_type: type: string maxLength: 300 minLength: 1 example: Instagram Reel description: type: string maxLength: 400 minLength: 1 example: Film a 20-second product demo and upload a draft to the Deal Folder. status: type: string maxLength: 80 minLength: 1 example: Revision Requested lifecycle_state: type: string maxLength: 80 minLength: 1 example: In-Progress file_action_state: $ref: '#/components/schemas/GetDealFolderFileActionState' applicable: description: Answers may use only applicable deliverables. type: boolean example: true effective_guidance: $ref: '#/components/schemas/GetDealFolderEffectiveGuidance' effective_guidance_basis: $ref: '#/components/schemas/GetDealFolderEffectiveGuidanceBasis' catalog_guidance: $ref: '#/components/schemas/GetDealFolderCatalogGuidance' completion_mode: $ref: '#/components/schemas/GetDealFolderCompletionMode' social_media: type: string maxLength: 80 minLength: 1 example: Instagram helper_message: type: string maxLength: 300 minLength: 1 example: Post the approved reel publicly. due_at_display: type: string maxLength: 120 minLength: 1 example: Aug 28, 2026 remaining_upload_slots: description: >- Remaining file capacity only. This is not outstanding required work and must not be recommended as a next action. type: integer maximum: 5 minimum: 0 example: 4 proof_of_work_required: type: boolean example: true needs_completion_handoff: type: boolean example: false files: type: array items: $ref: '#/components/schemas/GetDealFolderFile' maxItems: 5 source_ids: $ref: '#/components/schemas/InternalAiAssistantSourceIds' type: object additionalProperties: false GetDealFolderFocusedFile: required: - file_id - deliverable_id - status - file_action_state - comments - source_ids properties: file_id: type: integer minimum: 1 example: 901 deliverable_id: type: integer minimum: 1 example: 9121 slot_number: type: integer minimum: 1 example: 1 status: type: string maxLength: 80 minLength: 1 example: Revision Requested file_action_state: $ref: '#/components/schemas/GetDealFolderFileActionState' file_name: type: string maxLength: 255 minLength: 1 example: hydration-reel.mp4 latest_brand_comment: $ref: '#/components/schemas/GetDealFolderTypedComment' active_revision_request: $ref: '#/components/schemas/GetDealFolderTypedComment' comments: description: >- Bounded focused thread. Each row includes kind=comment or revision_request. type: array items: $ref: '#/components/schemas/GetDealFolderFileComment' maxItems: 5 source_ids: $ref: '#/components/schemas/InternalAiAssistantSourceIds' type: object additionalProperties: false InternalAiAssistantSourceIds: type: array items: type: string maxLength: 200 minLength: 1 maxItems: 500 uniqueItems: true example: - job:4821 - deal_folder:2051 - deal_folder_file:901 GetDealFolderEffectiveGuidance: description: >- instructed and applicable may be required work. recommended is optional. conditional, unknown, and unused slots never create required work. type: string enum: - recommended - not_expected - conditional - instructed - applicable example: applicable GetDealFolderEffectiveGuidanceBasis: type: string enum: - activity - deliverable_instructions - job_instructions - catalog - repost example: activity GetDealFolderCatalogGuidance: type: string enum: - recommended - not_expected - conditional example: recommended GetDealFolderCompletionMode: description: >- Final action after file approval while the deliverable remains In-Progress. Proof is mentioned only when proof_of_work_required is true. type: string enum: - publish_social_content - repost_existing_content - attend_appearance - complete_external_task - update_profile - submit_final_content - custom example: publish_social_content GetDealFolderFile: required: - file_id - deliverable_id - status - file_action_state - source_ids properties: file_id: type: integer minimum: 1 example: 901 deliverable_id: type: integer minimum: 1 example: 9121 slot_number: type: integer minimum: 1 example: 1 status: type: string maxLength: 80 minLength: 1 example: Revision Requested file_action_state: $ref: '#/components/schemas/GetDealFolderFileActionState' file_name: type: string maxLength: 255 minLength: 1 example: hydration-reel.mp4 latest_brand_comment: $ref: '#/components/schemas/GetDealFolderTypedComment' active_revision_request: $ref: '#/components/schemas/GetDealFolderTypedComment' source_ids: $ref: '#/components/schemas/InternalAiAssistantSourceIds' type: object additionalProperties: false GetDealFolderTypedComment: required: - comment_id - body - author_role - created_at_display - source_ids properties: comment_id: type: integer minimum: 1 example: 78 body: type: string maxLength: 400 minLength: 1 example: Thanks — waiting on the tighter crop. author_role: $ref: '#/components/schemas/GetDealFolderCommentAuthorRole' created_at_display: type: string maxLength: 120 minLength: 1 example: Aug 21, 2026 kind: $ref: '#/components/schemas/GetDealFolderCommentKind' source_ids: $ref: '#/components/schemas/InternalAiAssistantSourceIds' type: object additionalProperties: false GetDealFolderFileComment: required: - comment_id - body - author_role - created_at_display - kind - source_ids properties: comment_id: type: integer minimum: 1 example: 77 body: type: string maxLength: 400 minLength: 1 example: Please crop tighter on the product label. author_role: $ref: '#/components/schemas/GetDealFolderCommentAuthorRole' created_at_display: type: string maxLength: 120 minLength: 1 example: Aug 20, 2026 kind: $ref: '#/components/schemas/GetDealFolderCommentKind' source_ids: $ref: '#/components/schemas/InternalAiAssistantSourceIds' type: object additionalProperties: false GetDealFolderCommentAuthorRole: type: string enum: - brand - member - unknown example: brand GetDealFolderCommentKind: description: >- Internal AI projection classification. Public Deal Folder comment JSON does not expose comment_type. type: string enum: - comment - revision_request example: comment securitySchemes: bearerAuth: type: http description: >- JWT Bearer token authentication. Use the /api/login endpoint to obtain a token. scheme: bearer bearerFormat: JWT serverToServerApiKey: type: apiKey description: Server-to-Server API Key for internal/lambda/cron calls name: X-API-KEY in: header moglTurnToken: type: apiKey description: >- Signed short-lived AI turn token. The gateway derives athlete identity from this header; athlete IDs are never accepted in the tool body. name: X-Mogl-Turn-Token in: header ````