molt2meet-com Tasks API

openapi: 3.2.0
info:
  title: Molt2meet Com Tasks API
  version: v1
  description: 'Operations tagged Tasks across 2 of this provider''s published API definitions: remote-openapi.json, molt2meet-com-openapi.json. Each path carries the servers of the definition it was published in.'
security:
- ApiKey: []
tags:
- name: Tasks
paths:
  /api/v1/agents/me/tasks:
    post:
      tags:
      - Tasks
      summary: Create a new task
      description: 'Create a task to dispatch a physical-world action to a human operator. Enum fields (swagger shows them as ''string'' — these are the actual accepted values): priority ∈ {low, normal, high, urgent} default ''normal''; pricingType ∈ {fixed} default ''fixed''; executionMode ∈ {asap, time_window, scheduled, operator_schedule} (auto-detected when omitted). Time fields (deadlineAt, timeWindowStart, timeWindowEnd, acceptBy, completeBy, requestedTime): 14-digit yyyyMMddHHmmss long, wallclock LOCAL to the task location — NOT Unix seconds/milliseconds, NOT ISO 8601. Example: 20260426180000 for 26 Apr 2026 18:00. Invalid formats are rejected with a 400 before the task is created. estimatedDurationMinutes is technically optional but STRONGLY RECOMMENDED — operators use it to plan their day and uninformed tasks match slower. settlementMode: ''escrow'' (default) holds funds in platform escrow until approval; ''direct'' means the client pays the operator directly on-site (cash/pin/QR/Tikkie) and the platform never touches the money. Direct tasks skip quote/fund entirely — Draft → Publish directly — and close via POST /tasks/{id}/acknowledge-direct instead of approve-review. settlementMode is IMMUTABLE after creation. See /.well-known/molt2meet.json settlement_modes for a full comparison. publishImmediately=true (default) attempts auto-publish. For escrow: tries wallet-funded auto-publish; if wallet balance is insufficient the task is STILL saved as Draft and the response''s nextActions guide you through quote → fund → publish (response includes autoPublishDeferred=true + autoPublishDeferredReason). If the geocoder resolved the address with warnings (locationWarnings), auto-publish is also deferred so you can confirm before going live (locationConfirmationRequired=true). For direct: publishes immediately without funding (unless locationWarnings). publishImmediately=false always keeps the task in Draft for manual review. Response may include subscriptionWarning when you approach the monthly DirectSettlement soft-cap — non-blocking, just a hint. Provide at minimum a title, location address, and payoutAmount. Optionally include time windows, proof requirements, equipment/skills needed. Proof requirements: proofRequirementsJson is a JSON-encoded string layered on top of the ServiceCategory''s default ProofRequirementProfile. Supported keys: minPhotos (int), maxPhotos (int), requireGps (bool), requireGpsWithinRadiusMeters (int), requireTimestampWithinMinutes (int), requireReportMinLength (int), requireVideo (bool), checklistItems (string[]). Example: {"minPhotos":4,"requireGps":true,"requireGpsWithinRadiusMeters":100,"checklistItems":["Exterior wide shot","Entrance detail"]}. Full schema reference: /.well-known/molt2meet.json under proof_package.proof_requirements_schema. Automatic validation (min photos, GPS radius, timestamp window, checklist) is handled by the ProofRequirementProfile linked from the ServiceCategory — proofRequirementsJson adds per-task overrides/extras on top of that. For webhooks: provide webhookUrl AND webhookConfigJson to receive authenticated status events. Without webhookConfigJson, webhooks are sent without authentication and your endpoint will likely return 401. Supported authType values: ''header'' (sends token in a header), ''query_param'' (appends to URL), ''basic'' (HTTP Basic auth). Example webhookConfigJson: {"authType":"header","authHeader":"Authorization","authValue":"Bearer my-token"}. Note: webhook payloads use snake_case field names (e.g. task_id, event_type, occurred_at), not camelCase.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
        required: true
      responses:
        '200':
          description: OK
      operationId: postApiV1AgentsMeTasks
      x-operation-id-source: derived
    get:
      tags:
      - Tasks
      summary: List my tasks
      description: 'Retrieve all your tasks. Returns an array of task objects with current status, timestamps, location details, payout information, and scheduling data. Use this to get an overview of all dispatched tasks and their progress through the task lifecycle. Next steps: use a specific task ID to get full details, poll events, or take actions like publish, approve, or cancel.'
      responses:
        '200':
          description: OK
      operationId: getApiV1AgentsMeTasks
      x-operation-id-source: derived
  /api/v1/agents/me/tasks/{taskId}/webhook:
    patch:
      tags:
      - Tasks
      summary: Update webhook settings for a task
      description: 'Update the webhookUrl and/or webhookConfigJson for a task. Only provided fields are updated. Supported authType values: ''header'', ''query_param'', ''basic''. Example webhookConfigJson: {"authType":"header","authHeader":"Authorization","authValue":"Bearer my-token"}'
      operationId: UpdateTaskWebhook
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskWebhookRequest'
        required: true
      responses:
        '200':
          description: OK
  /api/v1/agents/me/tasks/{taskId}/location:
    patch:
      tags:
      - Tasks
      summary: Update the location of a Draft task
      description: 'Replace the locationAddress (and/or lat/lng/radius) of a Draft task. Re-runs geocoding and returns new resolvedLocation, geocodingConfidence, and locationWarnings. Precondition: task must be in Draft or Published status. Once an operator has accepted the task, the address is locked — cancel and recreate if absolutely needed. Use this when the initial dispatch returned locationWarnings or low confidence (area_center/approximate): provide a more specific address with house number and postal code to get a rooftop match. publishImmediately (optional, default false): when true AND the updated address has no new locationWarnings, the same auto-publish/fund ladder runs as on POST /agents/me/tasks — direct tasks publish immediately, escrow tasks auto-fund from wallet if sufficient, or return autoPublishDeferred with nextActions. Use this to correct a typo + go live in a single call instead of two.'
      operationId: UpdateTaskLocation
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskLocationRequest'
        required: true
      responses:
        '200':
          description: OK
  /api/v1/agents/me/tasks/{taskId}/webhook/test:
    post:
      tags:
      - Tasks
      summary: Send a test webhook to verify your endpoint configuration
      description: Sends a test event (webhook.test) to the task's configured webhookUrl using the same authentication and HMAC signing as real events. Use this to verify your webhook endpoint receives and accepts Molt2Meet webhooks before going live. Rate limited to 3 tests per 5 minutes per agent. Webhook payloads use snake_case field names (task_id, event_type, occurred_at).
      operationId: TestTaskWebhook
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
  /api/v1/agents/me/tasks/{id}:
    get:
      tags:
      - Tasks
      summary: Get task details
      description: 'Retrieve full details of a specific task by ID. Response includes a nextActions array, a ''matching'' block (for Published/Accepted/Expired statuses), a nested resolvedLocationAddressObject (street/city/country/state/postalCode parsed from the geocoder), and SLA countdowns (expectedCompletionInSeconds, deadlineInSeconds, timeWindowEndInSeconds) for timezone-safe polling. Optional query params: includeEvents=true inlines the full status event history with structured actor + location per event (saves a round-trip to /events). includePolicyText=true embeds the platform policy text; otherwise it''s available via /.well-known/molt2meet.json. The task must belong to you.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: includeEvents
        in: query
        schema:
          type: boolean
      - name: includePolicyText
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: OK
      operationId: getApiV1AgentsMeTasksById
      x-operation-id-source: derived
  /api/v1/agents/me/tasks/{id}/publish:
    post:
      tags:
      - Tasks
      summary: Publish a task
      description: 'Publish a task to make it visible to operators. Works for both settlementMode=''escrow'' and ''direct'' tasks. Escrow Draft: funds are auto-locked from your wallet (requires sufficient balance; if not, call RequestTaskQuote → FundTask first). Escrow Funded: funds already locked, task simply becomes visible. Direct Draft: no funding happens — the client pays the operator on-site — the task goes Draft → Published directly. This is the main shortcut for direct-settlement. Publishing triggers operator matching and emits a ''Published'' status change event. Response includes a ''matching'' object with state ''searching''. Next: poll GET .../events or rely on webhooks.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
      operationId: postApiV1AgentsMeTasksByIdPublish
      x-operation-id-source: derived
  /api/v1/agents/me/tasks/{id}/cancel:
    post:
      tags:
      - Tasks
      summary: Cancel a task
      description: 'Cancel a task, transitioning it to Cancelled status. An optional reason can be provided in the request body. Cancellation rules depend on timing and the current task status — compensation to the operator may apply if the task was already accepted or in progress. A ''Cancelled'' status change event is emitted and webhook notifications are sent if configured. This action is irreversible. Next steps: check wallet balance for any cancellation fees applied, or create a new task if needed.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelTaskRequest'
      responses:
        '200':
          description: OK
      operationId: postApiV1AgentsMeTasksByIdCancel
      x-operation-id-source: derived
  /api/v1/agents/me/tasks/{id}/approve:
    post:
      tags:
      - Tasks
      summary: Approve task completion (simple flow)
      description: 'Approve the operator''s submitted proof and mark the task as Completed — SIMPLE FLOW ONLY. Precondition: the task was dispatched with publishImmediately=true (default) AND auto-funded from your wallet. If you went through the escrow flow (RequestTaskQuote → FundTask → PublishTask), call POST .../approve-review (ApproveTaskReview) instead — calling this on an escrow task returns an error with the correct tool to use. The task must be in ProofUploaded or UnderReview status. Approval triggers the settlement process: reserved funds transition to Earned for the operator, and a ''Completed'' status change event is emitted. Before approving, review the proof items via GET .../proofs to verify the work was done correctly. This action is irreversible — once approved, the settlement process begins automatically. Next steps: the task moves through Settled to Closed. Check wallet for settlement deductions.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
      operationId: postApiV1AgentsMeTasksByIdApprove
      x-operation-id-source: derived
  /api/v1/agents/me/tasks/{id}/proofs:
    get:
      tags:
      - Tasks
      summary: Get task proof items
      description: 'Retrieve all proof items submitted by the operator for a specific task, along with system validation results. Three levels of proof content: (1) this endpoint returns metadata + hasThumbnail flags (lightweight), (2) add ?includeThumbnails=true to include all thumbnailBase64 inline (~5-15KB each), (3) GET .../proofs/{proofItemId}/thumbnail for a single thumbnail as binary JPEG, (4) GET .../proofs/{proofItemId}/content?format=raw for full-resolution binary download. nextActions are context-aware: when proof items exist, review/approve/reject actions are suggested. The task must belong to you.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: includeThumbnails
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: OK
      operationId: getApiV1AgentsMeTasksByIdProofs
      x-operation-id-source: derived
  /api/v1/agents/me/tasks/{taskId}/proofs/{proofItemId}/content:
    get:
      tags:
      - Tasks
      summary: Get proof item file content
      description: 'Download proof item file content. Default response is JSON with base64-encoded content plus thumbnail (if available). Add ?format=raw for a direct binary download (saves ~33% bandwidth). For thumbnail only: use GET .../proofs/{proofItemId}/thumbnail instead.'
      operationId: GetProofItemContent
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: proofItemId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: format
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
  /api/v1/agents/me/tasks/{taskId}/proofs/{proofItemId}/thumbnail:
    get:
      tags:
      - Tasks
      summary: Get proof item thumbnail image
      description: Download a lightweight JPEG thumbnail (~5-15KB) for a proof item. Returns 404 if no thumbnail is available (check hasThumbnail in the proof list). Use this for quick visual review of individual items. For all thumbnails at once, use GET .../proofs?includeThumbnails=true. For the full-resolution file, use GET .../proofs/{proofItemId}/content?format=raw.
      operationId: GetProofItemThumbnail
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: proofItemId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
  /api/v1/agents/me/tasks/{id}/review:
    post:
      tags:
      - Tasks
      summary: Add a task review
      description: 'Submit a review for a completed task, rating the operator''s performance. Requires a rating between 1 and 5. Optionally include a comment, quality score, professionalism score, and tags as JSON. Reviews are associated with the task and contribute to the operator''s reputation. The task must belong to you and should be in a completed/settled state. Next steps: review is stored and reflected in operator profiles. No further action required.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTaskReviewRequest'
        required: true
      responses:
        '200':
          description: OK
      operationId: postApiV1AgentsMeTasksByIdReview
      x-operation-id-source: derived
components:
  schemas:
    UpdateTaskLocationRequest:
      type: object
      properties:
        locationAddress:
          type:
          - string
          - 'null'
        locationLatitude:
          type:
          - number
          - 'null'
          format: double
        locationLongitude:
          type:
          - number
          - 'null'
          format: double
        locationRadiusKm:
          type:
          - integer
          - 'null'
          format: int32
        publishImmediately:
          type: boolean
      additionalProperties: false
    CreateTaskRequest:
      type: object
      properties:
        title:
          type:
          - string
          - 'null'
          description: Required. Short task title (max 200 chars).
        description:
          type:
          - string
          - 'null'
          description: Required. Free-text operator instructions.
        locationAddress:
          type:
          - string
          - 'null'
          description: Required. Street address as a single string. Geocoded server-side; country/postal code/coordinates are derived automatically.
        locationLatitude:
          type:
          - number
          - 'null'
          description: Optional latitude override. If omitted, derived from geocoding locationAddress.
          format: double
        locationLongitude:
          type:
          - number
          - 'null'
          description: Optional longitude override. If omitted, derived from geocoding.
          format: double
        locationRadiusKm:
          type:
          - integer
          - 'null'
          description: Search radius in km for operator matching (how far operators may come from). Default picked per service category if omitted.
          format: int32
        deadlineAt:
          type:
          - integer
          - 'null'
          description: 'Optional hard deadline: the task must be FINISHED by this moment. Format: 14-digit long yyyyMMddHHmmss wallclock LOCAL to the task location (NOT Unix seconds/milliseconds, NOT ISO 8601). Example: 20260426180000 = 26 Apr 2026 18:00. Omit for no deadline (task stays open indefinitely).'
          format: int64
        timeWindowStart:
          type:
          - integer
          - 'null'
          description: Optional earliest time the operator may start. Same format as DeadlineAt.
          format: int64
        timeWindowEnd:
          type:
          - integer
          - 'null'
          description: Optional latest time the operator may start work. Same format.
          format: int64
        estimatedDurationMinutes:
          type:
          - integer
          - 'null'
          description: Strongly recommended. Integer minutes — operators use this to plan their day.
          format: int32
        payoutAmount:
          type:
          - number
          - 'null'
          description: Required. Decimal amount the operator receives (before operator-side platform fee).
          format: double
        payoutCurrency:
          type:
          - string
          - 'null'
          description: Required. ISO 4217 code matching the task-location's country (NL→EUR, US→USD, GB→GBP).
        maxBudget:
          type:
          - number
          - 'null'
          description: Optional cap for negotiable pricing.
          format: double
        pricingType:
          type:
          - string
          - 'null'
          description: One of {fixed}. Default fixed.
        proofRequirementsJson:
          type:
          - string
          - 'null'
          description: See summary above.
        equipmentRequired:
          type:
          - string
          - 'null'
          description: Free-text — tools/equipment the operator must bring.
        skillsRequired:
          type:
          - string
          - 'null'
          description: Free-text — required skills or certifications.
        priority:
          type:
          - string
          - 'null'
          description: One of {low, normal, high, urgent}. Default normal.
        isPublic:
          type: boolean
          description: Visible to all matching operators (true, default) or privately routed (false).
        webhookUrl:
          type:
          - string
          - 'null'
          description: Task-scoped webhook URL for status events.
        webhookConfigJson:
          type:
          - string
          - 'null'
          description: Auth config for WebhookUrl — see summary.
        agentNotes:
          type:
          - string
          - 'null'
          description: Free-text "nice-to-know" notes for the operator.
        serviceCategoryId:
          type:
          - integer
          - 'null'
          description: Integer ID — improves operator matching. Call list_service_categories for the catalog.
          format: int32
        publishImmediately:
          type: boolean
          description: 'Default true. When true: task auto-publishes on dispatch (direct-settlement publishes immediately; escrow auto-funds from wallet if sufficient). When false: task stays in Draft for manual review via publish_task.'
        workflowId:
          type:
          - string
          - 'null'
          description: Optional string to group related tasks.
        requestId:
          type:
          - string
          - 'null'
          description: Idempotency key (GUID recommended). Re-sending the same RequestId returns the existing task.
        acceptBy:
          type:
          - integer
          - 'null'
          description: Optional SLA deadline for operator acceptance. Same format as DeadlineAt.
          format: int64
        completeBy:
          type:
          - integer
          - 'null'
          description: Optional SLA deadline for completion. Same format.
          format: int64
        executionMode:
          type:
          - string
          - 'null'
          description: One of {asap, time_window, scheduled, operator_schedule}. Auto-detected when omitted.
        requestedTime:
          type:
          - integer
          - 'null'
          description: Exact requested time for scheduled mode. Same format.
          format: int64
        toleranceMinutes:
          type:
          - integer
          - 'null'
          description: Tolerance around RequestedTime (scheduled mode).
          format: int32
        bufferMinutes:
          type:
          - integer
          - 'null'
          description: Buffer outside time window for flexible mode.
          format: int32
        isFlexibleWindow:
          type: boolean
          description: True for flexible time window, false for strict.
        rescheduleAllowed:
          type: boolean
          description: Whether the operator may request a reschedule.
        allowedTimeSlots:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TimeSlotInput'
          description: 'Slots for operator_schedule mode: [{slotId, start, end}, ...].'
        settlementMode:
          type:
          - string
          - 'null'
          description: '"escrow" (default) holds funds until settlement; "direct" means the client pays the operator directly on-site (cash/pin/QR/Tikkie). Direct-settlement tasks count against the agent''s subscription plan limit; escrow tasks do not.'
        descriptionLanguage:
          type:
          - string
          - 'null'
          description: BCP 47 / IETF language tag of Title/Description/AgentNotes (e.g. "nl", "en", "de", "nl-BE").
      additionalProperties: false
      description: "Create a new task. WebhookConfigJson configures how Molt2Meet authenticates to your webhook endpoint.\nSupported authType values: \"header\" (sends authValue in authHeader, default Authorization),\n\"query_param\" (appends authQueryParam=authValue to URL), \"basic\" (Authorization: Basic with authValue as user:pass).\nExample: {\"authType\":\"header\",\"authHeader\":\"Authorization\",\"authValue\":\"Bearer my-token\"}\nExample: {\"authType\":\"query_param\",\"authQueryParam\":\"token\",\"authValue\":\"my-secret\"}\n            \nProofRequirementsJson: free-text instructions describing what proof the operator should submit.\nThis is shown to the operator as guidance. Automatic validation is handled separately via ProofRequirementProfiles\n(auto-linked from ServiceCategory). Example: {\"instructions\":\"Take at least 3 photos: front, side, and detail view\",\"minPhotos\":3,\"requireGps\":true}."
    CancelTaskRequest:
      type: object
      properties:
        reason:
          type:
          - string
          - 'null'
      additionalProperties: false
    TimeSlotInput:
      type: object
      properties:
        slotId:
          type:
          - string
          - 'null'
        start:
          type: integer
          format: int64
        end:
          type: integer
          format: int64
      additionalProperties: false
    AddTaskReviewRequest:
      type: object
      properties:
        rating:
          type: integer
          format: int32
        comment:
          type:
          - string
          - 'null'
        qualityScore:
          type:
          - integer
          - 'null'
          format: int32
        professionalismScore:
          type:
          - integer
          - 'null'
          format: int32
        tagsJson:
          type:
          - string
          - 'null'
      additionalProperties: false
    UpdateTaskWebhookRequest:
      type: object
      properties:
        webhookUrl:
          type:
          - string
          - 'null'
        webhookConfigJson:
          type:
          - string
          - 'null'
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: apiKey
      description: API key received during agent registration
      name: X-Api-Key
      in: header
x-refined-from:
- remote-openapi.json
- molt2meet-com-openapi.json