openapi: 3.0.3
info:
  title: Upwork GraphQL 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
externalDocs:
  description: Upwork GraphQL API Documentation
  url: https://www.upwork.com/developer/documentation/graphql/api/docs/index.html
servers:
  - url: https://api.upwork.com
    description: Upwork Production API
tags:
  - name: Jobs
    description: >-
      Search and retrieve job postings on the Upwork marketplace.
  - name: Contracts
    description: >-
      Access and manage freelance contracts including terms, milestones, and time entries.
  - name: Profiles
    description: >-
      Query freelancer and client user profiles, skills, and ratings.
  - name: Messages
    description: >-
      Read and send messages within active contracts.
  - name: Authentication
    description: >-
      OAuth 2.0 token management for API access.
  - name: Webhooks
    description: >-
      Subscribe to platform events for real-time notifications.
security:
  - oauth2AuthCode: []
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:
        - Jobs
        - Contracts
        - Profiles
        - 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) {
                      marketplaceJobPostingsSearch(searchExpression: $searchExpression, paging: $paging) {
                        total
                        results {
                          id
                          title
                          description
                          skills { name }
                          budget { amount currency }
                          createdDateTime
                          client { id country }
                        }
                      }
                    }
                  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/jobs/search:
    get:
      operationId: searchJobsREST
      summary: Upwork Search Jobs
      description: >-
        Search for job postings on the Upwork marketplace using REST API.
        Returns paginated list of job listings matching search criteria.
      tags:
        - Jobs
      parameters:
        - name: q
          in: query
          description: Search query string
          schema:
            type: string
          example: "python developer"
        - name: skills
          in: query
          description: Comma-separated list of required skills
          schema:
            type: string
          example: "python,django"
        - name: budget
          in: query
          description: Budget range as min-max
          schema:
            type: string
          example: "1000-5000"
        - name: paging
          in: query
          description: Pagination as offset;count
          schema:
            type: string
          example: "0;10"
        - name: sort
          in: query
          description: Sort order for results
          schema:
            type: string
            enum:
              - recency
              - relevance
              - client_rating
          example: "recency"
      responses:
        '200':
          description: Paginated list of job postings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSearchResponse'
              examples:
                searchJobsREST200Example:
                  summary: Default searchJobsREST 200 response
                  x-microcks-default: true
                  value:
                    total: 1250
                    paging:
                      offset: 0
                      count: 10
                      total: 1250
                    jobs:
                      - id: "~0123456789abcdef"
                        title: "Python Developer for Data Pipeline"
                        status: "open"
                        budget:
                          amount: 5000
                          currency: "USD"
                        skills: ["Python", "Data Engineering"]
                        createdDateTime: "2025-03-15T14:30:00Z"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/v3/jobs/{job_id}:
    get:
      operationId: getJob
      summary: Upwork Get Job Details
      description: >-
        Retrieve detailed information for a specific job posting by its ID.
      tags:
        - Jobs
      parameters:
        - name: job_id
          in: path
          required: true
          description: The unique identifier of the job posting
          schema:
            type: string
          example: "~0123456789abcdef"
      responses:
        '200':
          description: Job posting details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
              examples:
                getJob200Example:
                  summary: Default getJob 200 response
                  x-microcks-default: true
                  value:
                    id: "~0123456789abcdef"
                    title: "Python Developer for Data Pipeline"
                    description: "Looking for an experienced Python developer..."
                    status: "open"
                    budget:
                      amount: 5000
                      currency: "USD"
        '404':
          description: Job not found
          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.00
                        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.00
                    currency: "USD"
        '404':
          description: Contract not found
          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

  /api/v3/profiles/v2/search/providers:
    get:
      operationId: searchFreelancers
      summary: Upwork Search Freelancers
      description: >-
        Search for freelancers on the Upwork marketplace by skills,
        availability, rating, and other criteria.
      tags:
        - Profiles
      parameters:
        - name: q
          in: query
          description: Search query string
          schema:
            type: string
          example: "python machine learning"
        - name: paging
          in: query
          description: Pagination as offset;count
          schema:
            type: string
          example: "0;10"
      responses:
        '200':
          description: List of freelancer profiles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreelancerSearchResponse'
              examples:
                searchFreelancers200Example:
                  summary: Default searchFreelancers 200 response
                  x-microcks-default: true
                  value:
                    total: 350
                    providers:
                      - id: "~abc123"
                        name: "Jane Smith"
                        title: "Senior Python Developer"
                        rate: 75.00
                        currency: "USD"
                        rating: 4.95
                        skills: ["Python", "Machine Learning", "Data Science"]
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/v3/profiles/v2/users/{user_id}:
    get:
      operationId: getFreelancerProfile
      summary: Upwork Get Freelancer Profile
      description: >-
        Retrieve the public profile for a specific freelancer or user.
      tags:
        - Profiles
      parameters:
        - name: user_id
          in: path
          required: true
          description: The unique identifier or username of the user
          schema:
            type: string
          example: "~abc123"
      responses:
        '200':
          description: Freelancer profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreelancerProfile'
              examples:
                getFreelancerProfile200Example:
                  summary: Default getFreelancerProfile 200 response
                  x-microcks-default: true
                  value:
                    id: "~abc123"
                    name: "Jane Smith"
                    title: "Senior Python Developer"
                    rate: 75.00
                    rating: 4.95
                    jobsCompleted: 48
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/auth/v1/oauth/token:
    post:
      operationId: getOAuthToken
      summary: Upwork Get OAuth2 Access Token
      description: >-
        Exchange an authorization code for an OAuth2 access token and
        refresh token. Supports both authorization_code and refresh_token
        grant types.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  enum:
                    - authorization_code
                    - refresh_token
                  description: OAuth2 grant type
                  example: "authorization_code"
                client_id:
                  type: string
                  description: Application client identifier
                  example: "client-abc123"
                client_secret:
                  type: string
                  description: Application client secret
                  example: "secret-xyz789"
                code:
                  type: string
                  description: Authorization code (required for authorization_code grant)
                  example: "auth-code-123"
                refresh_token:
                  type: string
                  description: Refresh token (required for refresh_token grant)
                  example: "refresh-token-abc"
                redirect_uri:
                  type: string
                  description: Redirect URI matching the one used in authorization
                  example: "https://myapp.example.com/callback"
      responses:
        '200':
          description: OAuth2 token response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthToken'
              examples:
                getOAuthToken200Example:
                  summary: Default getOAuthToken 200 response
                  x-microcks-default: true
                  value:
                    access_token: "eyJhbGciOiJSUzI1NiJ9.example.token"
                    token_type: "bearer"
                    refresh_token: "refresh-token-xyz789"
                    expires_in: 86400
        '401':
          description: Invalid client credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  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

  schemas:
    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"

    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

    Job:
      type: object
      description: A job posting on the Upwork marketplace
      properties:
        id:
          type: string
          description: Unique identifier for the job
          example: "~0123456789abcdef"
        title:
          type: string
          description: Title of the job posting
          example: "Python Developer for Data Pipeline"
        description:
          type: string
          description: Detailed description of the job requirements
          example: "Looking for an experienced Python developer..."
        status:
          type: string
          description: Current status of the job posting
          enum:
            - open
            - closed
            - draft
          example: "open"
        budget:
          $ref: '#/components/schemas/Budget'
        skills:
          type: array
          description: Required skills for the job
          items:
            $ref: '#/components/schemas/Skill'
        createdDateTime:
          type: string
          format: date-time
          description: When the job was posted
          example: "2025-03-15T14:30:00Z"
        client:
          $ref: '#/components/schemas/Client'
        jobType:
          type: string
          description: Type of job (hourly or fixed-price)
          enum:
            - hourly
            - fixed-price
          example: "fixed-price"
        duration:
          type: string
          description: Expected duration of the project
          example: "1-3 months"
        experienceLevel:
          type: string
          description: Required experience level
          enum:
            - entry
            - intermediate
            - expert
          example: "intermediate"

    JobSearchResponse:
      type: object
      description: Paginated job search results
      properties:
        total:
          type: integer
          description: Total number of matching jobs
          example: 1250
        paging:
          $ref: '#/components/schemas/Paging'
        jobs:
          type: array
          description: List of job postings
          items:
            $ref: '#/components/schemas/Job'

    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.00
        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"

    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'

    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"

    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."

    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'

    FreelancerProfile:
      type: object
      description: A freelancer profile on Upwork
      properties:
        id:
          type: string
          description: Unique identifier for the freelancer
          example: "~abc123"
        name:
          type: string
          description: Full name of the freelancer
          example: "Jane Smith"
        title:
          type: string
          description: Professional title or headline
          example: "Senior Python Developer"
        description:
          type: string
          description: Profile overview/bio
          example: "Experienced Python developer with 8 years..."
        rate:
          type: number
          description: Hourly rate
          example: 75.00
        currency:
          type: string
          description: Rate currency
          example: "USD"
        rating:
          type: number
          description: Average client rating (0-5)
          example: 4.95
        jobsCompleted:
          type: integer
          description: Total number of completed jobs
          example: 48
        skills:
          type: array
          description: Skills listed on the profile
          items:
            type: string
          example: ["Python", "Machine Learning", "Data Science"]
        country:
          type: string
          description: Country of the freelancer
          example: "US"
        availability:
          type: string
          description: Current availability status
          enum:
            - full-time
            - part-time
            - not-available
          example: "full-time"

    FreelancerSearchResponse:
      type: object
      description: Paginated freelancer search results
      properties:
        total:
          type: integer
          description: Total number of matching freelancers
          example: 350
        providers:
          type: array
          description: List of freelancer profiles
          items:
            $ref: '#/components/schemas/FreelancerProfile'

    Budget:
      type: object
      description: Budget for a job posting
      properties:
        amount:
          type: number
          description: Budget amount
          example: 5000.00
        currency:
          type: string
          description: Budget currency
          example: "USD"

    Skill:
      type: object
      description: A skill associated with a job or profile
      properties:
        name:
          type: string
          description: Skill name
          example: "Python"
        uid:
          type: string
          description: Unique identifier for the skill
          example: "skill-123"

    Client:
      type: object
      description: A client on the Upwork platform
      properties:
        id:
          type: string
          description: Unique identifier for the client
          example: "~def456"
        country:
          type: string
          description: Client country code
          example: "US"
        totalSpent:
          type: number
          description: Total amount spent on Upwork
          example: 50000.00
        rating:
          type: number
          description: Client rating
          example: 4.8

    Paging:
      type: object
      description: Pagination information
      properties:
        offset:
          type: integer
          description: Current offset
          example: 0
        count:
          type: integer
          description: Number of items returned
          example: 10
        total:
          type: integer
          description: Total number of items available
          example: 1250

    OAuthToken:
      type: object
      description: OAuth2 access token response
      properties:
        access_token:
          type: string
          description: The access token for API requests
          example: "eyJhbGciOiJSUzI1NiJ9.example.token"
        token_type:
          type: string
          description: Token type (always bearer)
          example: "bearer"
        refresh_token:
          type: string
          description: Token for obtaining new access tokens
          example: "refresh-token-xyz789"
        expires_in:
          type: integer
          description: Token lifetime in seconds
          example: 86400

    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