Upwork Contracts API
Access and manage freelance contracts including terms, milestones, and time entries.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/upwork-contracts-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.0.3
info:
title: Upwork GraphQL Authentication Contracts API
description: The primary Upwork API surface, providing GraphQL queries and mutations for job search, profile access, contract management, and messaging. The API is accessed at a single GraphQL endpoint using POST requests with JSON bodies containing queries and variables. Authentication uses OAuth 2.0 authorization code flow with Bearer tokens. GraphQL subscriptions are supported for real-time webhook event notifications.
version: 1.0.0
contact:
name: Upwork Developer Support
url: https://support.upwork.com/hc/en-us/sections/17976982721555-Upwork-API
termsOfService: https://www.upwork.com/legal
x-generated-from: documentation
servers:
- url: https://api.upwork.com
description: Upwork Production API
security:
- oauth2AuthCode: []
tags:
- name: Contracts
description: Access and manage freelance contracts including terms, milestones, and time entries.
paths:
/graphql:
post:
operationId: executeGraphQL
summary: Upwork Execute GraphQL Query or Mutation
description: Execute a GraphQL query, mutation, or subscription against the Upwork API. All GraphQL operations are sent as POST requests to this endpoint with a JSON body containing the query, optional variables, and optional operation name. Returns JSON with data and optional errors fields.
tags:
- Contracts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLRequest'
examples:
searchJobs:
summary: Search for jobs using marketplaceJobPostingsSearch
value:
query: "query SearchJobs($searchExpression: String, $paging: PagingInput) {\n marketplaceJobPostingsSearch(searchExpression: $searchExpression, paging: $paging) {\n total\n results {\n id\n title\n description\n skills { name }\n budget { amount currency }\n createdDateTime\n client { id country }\n }\n }\n}\n"
variables:
searchExpression: python developer
paging:
offset: 0
count: 10
responses:
'200':
description: GraphQL response with data or errors
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLResponse'
examples:
jobSearchResponse:
summary: Job search results
x-microcks-default: true
value:
data:
marketplaceJobPostingsSearch:
total: 1250
results:
- id: ~0123456789abcdef
title: Python Developer for Data Pipeline
description: Looking for an experienced Python developer...
skills:
- name: Python
- name: Data Engineering
budget:
amount: 5000
currency: USD
createdDateTime: '2025-03-15T14:30:00Z'
'401':
description: Unauthorized - invalid or missing OAuth2 token
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v3/hr/v2/contracts:
get:
operationId: listContracts
summary: Upwork List Contracts
description: Retrieve a list of contracts for the authenticated user. Includes both active and completed contracts with status, terms, and financial data.
tags:
- Contracts
parameters:
- name: status
in: query
description: Filter by contract status
schema:
type: string
enum:
- active
- closed
- paused
example: active
- name: buyer_team__reference
in: query
description: Filter by buyer team reference ID
schema:
type: string
example: team-abc123
- name: paging
in: query
description: Pagination as offset;count
schema:
type: string
example: 0;20
responses:
'200':
description: List of contracts
content:
application/json:
schema:
$ref: '#/components/schemas/ContractListResponse'
examples:
listContracts200Example:
summary: Default listContracts 200 response
x-microcks-default: true
value:
total: 25
contracts:
- id: contract-abc123
status: active
jobTitle: Python Developer for Data Pipeline
freelancerName: Jane Smith
rate: 75.0
currency: USD
startedTime: '2025-01-15T10:00:00Z'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v3/hr/v2/contracts/{contract_id}:
get:
operationId: getContract
summary: Upwork Get Contract Details
description: Retrieve detailed information for a specific contract including terms, milestones, time entries, and financial summary.
tags:
- Contracts
parameters:
- name: contract_id
in: path
required: true
description: The unique identifier of the contract
schema:
type: string
example: contract-abc123
responses:
'200':
description: Contract details
content:
application/json:
schema:
$ref: '#/components/schemas/Contract'
examples:
getContract200Example:
summary: Default getContract 200 response
x-microcks-default: true
value:
id: contract-abc123
status: active
jobTitle: Python Developer for Data Pipeline
rate: 75.0
currency: USD
'404':
description: Contract not found
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
Contract:
type: object
description: A freelance contract between a client and freelancer on Upwork
properties:
id:
type: string
description: Unique identifier for the contract
example: contract-abc123
status:
type: string
description: Current status of the contract
enum:
- active
- paused
- closed
example: active
jobTitle:
type: string
description: Title of the job associated with this contract
example: Python Developer for Data Pipeline
freelancerId:
type: string
description: ID of the freelancer on the contract
example: ~abc123
freelancerName:
type: string
description: Name of the freelancer
example: Jane Smith
clientId:
type: string
description: ID of the client
example: ~def456
rate:
type: number
description: Hourly or fixed rate for the contract
example: 75.0
currency:
type: string
description: Currency for the contract rate
example: USD
startedTime:
type: string
format: date-time
description: When the contract started
example: '2025-01-15T10:00:00Z'
endedTime:
type: string
format: date-time
description: When the contract ended (if closed)
example: '2025-03-15T10:00:00Z'
GraphQLRequest:
type: object
description: A GraphQL request body containing the operation to execute
required:
- query
properties:
query:
type: string
description: The GraphQL query or mutation string
example: 'query { marketplaceJobPostingsSearch(searchExpression: "python") { total } }'
variables:
type: object
description: Variables for the GraphQL operation
additionalProperties: true
operationName:
type: string
description: Name of the operation to execute (for documents with multiple operations)
example: SearchJobs
APIError:
type: object
description: API error response
properties:
error:
type: string
description: Error code
example: unauthorized
message:
type: string
description: Human-readable error message
example: Authentication failed. Please check your credentials.
code:
type: integer
description: HTTP status code
example: 401
ContractListResponse:
type: object
description: Paginated list of contracts
properties:
total:
type: integer
description: Total number of contracts
example: 25
contracts:
type: array
description: List of contracts
items:
$ref: '#/components/schemas/Contract'
GraphQLError:
type: object
description: A GraphQL error
properties:
message:
type: string
description: Human-readable error message
example: Unauthorized access
locations:
type: array
description: Source locations of the error
items:
type: object
properties:
line:
type: integer
example: 2
column:
type: integer
example: 5
path:
type: array
description: Path to the field that caused the error
items:
type: string
GraphQLResponse:
type: object
description: A GraphQL response containing data or errors
properties:
data:
type: object
description: The response data for the operation
additionalProperties: true
errors:
type: array
description: List of GraphQL errors if the operation failed
items:
$ref: '#/components/schemas/GraphQLError'
securitySchemes:
oauth2AuthCode:
type: oauth2
description: OAuth 2.0 authorization code flow for Upwork API access. Obtain an authorization code by redirecting users to the Upwork OAuth consent page, then exchange for access and refresh tokens.
flows:
authorizationCode:
authorizationUrl: https://www.upwork.com/ab/account-security/oauth2/authorize
tokenUrl: https://www.upwork.com/api/v3/oauth2/token
scopes:
openid: Access to user identity information
email: Access to user email
profile: Access to user profile data
jobs:read: Read job postings
contracts:read: Read contract data
messages:read: Read messages
messages:write: Send messages
profiles:read: Read freelancer profiles
reports:read: Read financial reports
externalDocs:
description: Upwork GraphQL API Documentation
url: https://www.upwork.com/developer/documentation/graphql/api/docs/index.html