Deals and opportunities

Pipelines, deals and the forecast, plus the shared opportunity board.

11 endpoints· 4 called live· 7 not exercised here· verified against http://127.0.0.1:8741

11 endpoints

GET/api/v1/salesshift/dealsCalled liveDeals, optionally filtered by pipeline and status.

Auth: get_org_user
Scope: organization
Success: 200 · application/json
Envelope: success+data

Query parameters

Name	Type	Required	Notes
pipeline_id	string(uuid)?	optional
status_filter	string?	optional

Request

curl

curl 'https://api.vxcloud.io/api/v1/salesshift/deals' \
  -H "Authorization: Bearer $SS_TOKEN"

Response · 200

Observed shape

{
  "success": "bool",
  "data": [
    {
      "id": "str",
      "organization_id": "str",
      "pipeline_id": "str",
      "stage_id": "str",
      "name": "str",
      "amount": "float",
      "currency": "str",
      "expected_close": "null",
      "contact_id": "null",
      "company_id": "null",
      "status": "str",
      "lost_reason": "null",
      "tags": [
        "<empty list>"
      ],
      "created_at": "str",
      "updated_at": "str"
    },
    "...x22"
  ]
}

Observed on 2026-08-06 — keys are real, values are the types that came back.

#get-api-v1-salesshift-dealsdeals_router · vxcloud_fastapiclient/app/services/salesshift/deals_router.py:99Called against http://127.0.0.1:8741 on 2026-08-06 with a real JWT; the response matched the shape recorded below.

POST/api/v1/salesshift/dealsNot exercised hereCreate a deal, defaulting to the org's first pipeline and stage when none is given.

Auth: get_org_user
Scope: organization
Success: 201 · application/json
Envelope: bare-model

Request body (required) — DealCreate

Field	Type	Required	Notes
name	string	required
pipeline_id	string(uuid)?	optional
stage_id	string(uuid)?	optional
amount	number?	optional
currency	string	optional	Default `"USD"`.
expected_close	string(date)?	optional
contact_id	string(uuid)?	optional
company_id	string(uuid)?	optional
tags	string[]	optional

Values in the request below are typed placeholders, not sample data.

Request

curl

curl -X POST 'https://api.vxcloud.io/api/v1/salesshift/deals' \
  -H "Authorization: Bearer $SS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "<string>", "pipeline_id": "<string(uuid)>", "stage_id": "<string(uuid)>", "amount": 0, "currency": "USD", "expected_close": "<string(date)>", "contact_id": "<string(uuid)>", "company_id": "<string(uuid)>", "tags": [ "<string>" ] }'

Response · 201

DealOut fields

{
  "id": "string(uuid)",
  "organization_id": "string(uuid)",
  "pipeline_id": "string(uuid)",
  "stage_id": "string(uuid)",
  "name": "string",
  "amount": "number?",
  "currency": "string",
  "expected_close": "string(date)?",
  "contact_id": "string(uuid)?",
  "company_id": "string(uuid)?",
  "status": "string",
  "lost_reason": "string?",
  "tags": "string[]?",
  "created_at": "string(date-time)",
  "updated_at": "string(date-time)"
}

Fields declared by DealOut; values shown are types.

Errors

Status	detail
400	`Pipeline has no stages`

#post-api-v1-salesshift-dealsdeals_router · vxcloud_fastapiclient/app/services/salesshift/deals_router.py:121Implemented and read in source for this inventory, but not exercised against a running server here. Treat as undemonstrated until someone calls it.

PUT/api/v1/salesshift/deals/{deal_id}Not exercised hereUpdate a deal from a partial payload.

Auth: get_org_user
Scope: organization
Success: 200 · application/json
Envelope: bare-model

Path parameters

Name	Type	Required	Notes
deal_id	string(uuid)	required

Request body (required) — DealUpdate

Field	Type	Required
name	string?	optional
amount	number?	optional
currency	string?	optional
expected_close	string(date)?	optional
contact_id	string(uuid)?	optional
company_id	string(uuid)?	optional
status	string?	optional
lost_reason	string?	optional
tags	string[]?	optional

Values in the request below are typed placeholders, not sample data.

Request

curl

curl -X PUT 'https://api.vxcloud.io/api/v1/salesshift/deals/{deal_id}' \
  -H "Authorization: Bearer $SS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "<string>", "amount": 0, "currency": "<string>", "expected_close": "<string(date)>", "contact_id": "<string(uuid)>", "company_id": "<string(uuid)>", "status": "<string>", "lost_reason": "<string>", "tags": [ "<string>" ] }'

Response · 200

DealOut fields

{
  "id": "string(uuid)",
  "organization_id": "string(uuid)",
  "pipeline_id": "string(uuid)",
  "stage_id": "string(uuid)",
  "name": "string",
  "amount": "number?",
  "currency": "string",
  "expected_close": "string(date)?",
  "contact_id": "string(uuid)?",
  "company_id": "string(uuid)?",
  "status": "string",
  "lost_reason": "string?",
  "tags": "string[]?",
  "created_at": "string(date-time)",
  "updated_at": "string(date-time)"
}

Fields declared by DealOut; values shown are types.

Errors

Status	detail
404	`Deal not found`

#put-api-v1-salesshift-deals-deal-iddeals_router · vxcloud_fastapiclient/app/services/salesshift/deals_router.py:162Implemented and read in source for this inventory, but not exercised against a running server here. Treat as undemonstrated until someone calls it.

DELETE/api/v1/salesshift/deals/{deal_id}Not exercised hereDelete a deal.

Auth: get_org_user
Scope: organization
Success: 200 · application/json
Envelope: success+custom

Path parameters

Name	Type	Required	Notes
deal_id	string(uuid)	required

Request

curl

curl -X DELETE 'https://api.vxcloud.io/api/v1/salesshift/deals/{deal_id}' \
  -H "Authorization: Bearer $SS_TOKEN"

Response · 200

Top-level keys

{
  "success": "…"
}

Top-level keys read from the handler's return statements.

Errors

Status	detail
404	`Deal not found`

#delete-api-v1-salesshift-deals-deal-iddeals_router · vxcloud_fastapiclient/app/services/salesshift/deals_router.py:233Implemented and read in source for this inventory, but not exercised against a running server here. Treat as undemonstrated until someone calls it.

PUT/api/v1/salesshift/deals/{deal_id}/moveNot exercised herePowers drag-and-drop Kanban.

Powers drag-and-drop Kanban. Won/lost stages update deal status.

Auth: get_org_user
Scope: organization
Success: 200 · application/json
Envelope: bare-model

Path parameters

Name	Type	Required	Notes
deal_id	string(uuid)	required

Request body (required) — DealMove

Field	Type	Required	Notes
stage_id	string(uuid)	required

Values in the request below are typed placeholders, not sample data.

Request

curl

curl -X PUT 'https://api.vxcloud.io/api/v1/salesshift/deals/{deal_id}/move' \
  -H "Authorization: Bearer $SS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "stage_id": "<string(uuid)>" }'

Response · 200

DealOut fields

{
  "id": "string(uuid)",
  "organization_id": "string(uuid)",
  "pipeline_id": "string(uuid)",
  "stage_id": "string(uuid)",
  "name": "string",
  "amount": "number?",
  "currency": "string",
  "expected_close": "string(date)?",
  "contact_id": "string(uuid)?",
  "company_id": "string(uuid)?",
  "status": "string",
  "lost_reason": "string?",
  "tags": "string[]?",
  "created_at": "string(date-time)",
  "updated_at": "string(date-time)"
}

Fields declared by DealOut; values shown are types.

Errors

Status	detail
404	`Deal not found`
404	`Stage not found`

#put-api-v1-salesshift-deals-deal-id-movedeals_router · vxcloud_fastapiclient/app/services/salesshift/deals_router.py:183Implemented and read in source for this inventory, but not exercised against a running server here. Treat as undemonstrated until someone calls it.

GET/api/v1/salesshift/deals/forecastCalled liveWeighted pipeline forecast: sum(amount * stage.win_probability).

Auth: get_org_user
Scope: organization
Success: 200 · application/json
Envelope: success+data

Request

curl

curl 'https://api.vxcloud.io/api/v1/salesshift/deals/forecast' \
  -H "Authorization: Bearer $SS_TOKEN"

Response · 200

Observed shape

{
  "success": "bool",
  "data": {
    "stages": [
      {
        "stage": "...",
        "deal_count": "...",
        "total_value": "...",
        "weighted_value": "..."
      },
      "...x6"
    ],
    "total_pipeline": "float",
    "weighted_forecast": "float"
  }
}

Observed on 2026-08-06 — keys are real, values are the types that came back.

#get-api-v1-salesshift-deals-forecastdeals_router · vxcloud_fastapiclient/app/services/salesshift/deals_router.py:250Called against http://127.0.0.1:8741 on 2026-08-06 with a real JWT; the response matched the shape recorded below.

GET/api/v1/salesshift/opportunitiesCalled liveOpen, user-posted opportunities; retired platform seed rows are excluded.

Auth: get_org_user
Scope: organization
Success: 200 · application/json
Envelope: success+custom

Query parameters

Name	Type	Required	Notes
q	string	optional	Default `""`.
category	string	optional	Default `""`.

Request

curl

curl 'https://api.vxcloud.io/api/v1/salesshift/opportunities' \
  -H "Authorization: Bearer $SS_TOKEN"

Response · 200

Observed shape

{
  "success": "bool",
  "data": [
    {
      "id": "str",
      "title": "str",
      "description": "str",
      "category": "str",
      "skills": [
        "...",
        "...x2"
      ],
      "company_name": "str",
      "contact_email": "str",
      "location": "null",
      "budget_min": "float",
      "budget_max": "float",
      "currency": "str",
      "duration": "str",
      "status": "str",
      "is_platform": "bool",
      "posted_by": "str",
      "applications_count": "int",
      "created_at": "str",
      "my_application": "null"
    },
    "...x2"
  ],
  "categories": [
    "str",
    "...x10"
  ]
}

Observed on 2026-08-06 — keys are real, values are the types that came back.

#get-api-v1-salesshift-opportunitiesopportunities_router · vxcloud_fastapiclient/app/services/salesshift/opportunities_router.py:90Called against http://127.0.0.1:8741 on 2026-08-06 with a real JWT; the response matched the shape recorded below.

POST/api/v1/salesshift/opportunitiesNot exercised herePost an opportunity to the shared board.

Auth: get_org_user
Scope: organization
Success: 201 · application/json
Envelope: success+data

Request body (required) — OpportunityIn

Field	Type	Required	Notes
title	string	required	≤ 300 chars.
description	string	required
category	string	optional	Default `"Other"`.
skills	string[]	optional	Default `[]`.
company_name	string	optional	Default `""`.
contact_email	string	optional	Default `""`.
location	string	optional	Default `""`.
budget_min	number?	optional
budget_max	number?	optional
duration	string	optional	Default `""`.

Values in the request below are typed placeholders, not sample data.

Request

curl

curl -X POST 'https://api.vxcloud.io/api/v1/salesshift/opportunities' \
  -H "Authorization: Bearer $SS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "title": "<string>", "description": "<string>", "category": "Other", "skills": [], "company_name": "", "contact_email": "", "location": "", "budget_min": 0, "budget_max": 0, "duration": "" }'

Response · 201

Top-level keys

{
  "data": "…",
  "success": "…"
}

Top-level keys read from the handler's return statements.

#post-api-v1-salesshift-opportunitiesopportunities_router · vxcloud_fastapiclient/app/services/salesshift/opportunities_router.py:127Implemented and read in source for this inventory, but not exercised against a running server here. Treat as undemonstrated until someone calls it.

POST/api/v1/salesshift/opportunities/{opportunity_id}/applyNot exercised hereApply to an open opportunity.

Auth: get_org_user
Scope: organization
Success: 200 · application/json
Envelope: success+custom

Path parameters

Name	Type	Required	Notes
opportunity_id	string(uuid)	required

Request body (required) — ApplyIn

Field	Type	Required	Notes
message	string	required
proposed_rate	string	optional	Default `""`.

Values in the request below are typed placeholders, not sample data.

Request

curl

curl -X POST 'https://api.vxcloud.io/api/v1/salesshift/opportunities/{opportunity_id}/apply' \
  -H "Authorization: Bearer $SS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "message": "<string>", "proposed_rate": "" }'

Response · 200

Top-level keys

{
  "email_sent": "…",
  "success": "…"
}

Top-level keys read from the handler's return statements.

Errors

Status	detail
404	`Opportunity not found or closed`
409	`Already applied to this opportunity`

#post-api-v1-salesshift-opportunities-opportunity-id-applyopportunities_router · vxcloud_fastapiclient/app/services/salesshift/opportunities_router.py:148Implemented and read in source for this inventory, but not exercised against a running server here. Treat as undemonstrated until someone calls it.

POST/api/v1/salesshift/opportunities/{opportunity_id}/convertNot exercised hereOpportunity → lead (contact) → contract (deal) in the default pipeline.

Auth: get_org_user
Scope: organization
Success: 200 · application/json
Envelope: success+custom

Path parameters

Name	Type	Required	Notes
opportunity_id	string(uuid)	required

Request

curl

curl -X POST 'https://api.vxcloud.io/api/v1/salesshift/opportunities/{opportunity_id}/convert' \
  -H "Authorization: Bearer $SS_TOKEN"

Response · 200

Top-level keys

{
  "already_converted": "…",
  "contact_id": "…",
  "deal_id": "…",
  "success": "…"
}

Top-level keys read from the handler's return statements.

Errors

Status	detail
404	`Opportunity not found`
400	`No pipeline yet — open Contracts once first`
400	`Pipeline has no stages`

#post-api-v1-salesshift-opportunities-opportunity-id-convertopportunities_router · vxcloud_fastapiclient/app/services/salesshift/opportunities_router.py:215Implemented and read in source for this inventory, but not exercised against a running server here. Treat as undemonstrated until someone calls it.

GET/api/v1/salesshift/pipelinesCalled liveThe organization's deal pipelines and their stages, seeding a default pipeline on first use.

Auth: get_org_user
Scope: organization
Success: 200 · application/json
Envelope: success+data

Request

curl

curl 'https://api.vxcloud.io/api/v1/salesshift/pipelines' \
  -H "Authorization: Bearer $SS_TOKEN"

Response · 200

Observed shape

{
  "success": "bool",
  "data": [
    {
      "id": "str",
      "organization_id": "str",
      "name": "str",
      "is_default": "bool",
      "is_active": "bool",
      "stages": [
        "...",
        "...x6"
      ]
    },
    "...x1"
  ]
}

Observed on 2026-08-06 — keys are real, values are the types that came back.

#get-api-v1-salesshift-pipelinesdeals_router · vxcloud_fastapiclient/app/services/salesshift/deals_router.py:81Called against http://127.0.0.1:8741 on 2026-08-06 with a real JWT; the response matched the shape recorded below.