openapi: 3.0.3
info:
  title: Upwork GraphQL Authentication Jobs 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: Jobs
  description: Search and retrieve job postings on the Upwork marketplace.
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
      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/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
components:
  schemas:
    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
    Budget:
      type: object
      description: Budget for a job posting
      properties:
        amount:
          type: number
          description: Budget amount
          example: 5000.0
        currency:
          type: string
          description: Budget currency
          example: USD
    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
    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
    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
    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'
    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.0
        rating:
          type: number
          description: Client rating
          example: 4.8
    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'
    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
  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