Upwork Messages API
Read and send messages within active contracts.
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-messages-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Upwork GraphQL Messages 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: Messages
description: Read and send messages within active contracts.
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:
- Messages
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/messages/v3/rooms/{room_id}/messages:
get:
operationId: listMessages
summary: Upwork List Messages
description: Retrieve messages from a contract messaging room. Returns paginated message history ordered by time.
tags:
- Messages
parameters:
- name: room_id
in: path
required: true
description: The unique identifier of the messaging room
schema:
type: string
example: room-xyz789
- name: paging
in: query
description: Pagination parameters
schema:
type: string
example: 0;20
responses:
'200':
description: List of messages
content:
application/json:
schema:
$ref: '#/components/schemas/MessageListResponse'
examples:
listMessages200Example:
summary: Default listMessages 200 response
x-microcks-default: true
value:
total: 48
messages:
- id: msg-abc123
text: Hi, let's discuss the project requirements
createdDateTime: '2025-03-15T14:30:00Z'
authorId: user-12345
authorName: Jane Smith
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: sendMessage
summary: Upwork Send Message
description: Send a message to a contract messaging room.
tags:
- Messages
parameters:
- name: room_id
in: path
required: true
description: The unique identifier of the messaging room
schema:
type: string
example: room-xyz789
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageCreate'
examples:
sendMessageRequestExample:
summary: Default sendMessage request
x-microcks-default: true
value:
message: Thank you for the update, I'll review the code shortly.
responses:
'200':
description: Message sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
examples:
sendMessage200Example:
summary: Default sendMessage 200 response
x-microcks-default: true
value:
id: msg-def456
text: Thank you for the update, I'll review the code shortly.
createdDateTime: '2025-03-15T15:00:00Z'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
MessageCreate:
type: object
description: Request body for sending a message
required:
- message
properties:
message:
type: string
description: The message text to send
example: Thank you for the update, I'll review shortly.
Message:
type: object
description: A message in a contract messaging room
properties:
id:
type: string
description: Unique identifier for the message
example: msg-abc123
text:
type: string
description: The message text content
example: Hi, let's discuss the project requirements
createdDateTime:
type: string
format: date-time
description: When the message was sent
example: '2025-03-15T14:30:00Z'
authorId:
type: string
description: ID of the message author
example: user-12345
authorName:
type: string
description: Name of the message author
example: Jane Smith
roomId:
type: string
description: ID of the messaging room
example: room-xyz789
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
MessageListResponse:
type: object
description: Paginated list of messages
properties:
total:
type: integer
description: Total number of messages
example: 48
messages:
type: array
description: List of messages
items:
$ref: '#/components/schemas/Message'
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'
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
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