{
  "openapi": "3.1.0",
  "info": {
    "title": "Upwork API",
    "version": "1.0.0",
    "description": "Search public Upwork job postings by keyword or by an Upwork search URL, and read one posting in full. Budgets are parsed rather than passed through as text, and every response reports how many postings were expanded into their full record (enrichedJobs) against how many came back — because per-posting expansion is intermittently refused upstream and the response says so rather than hiding it."
  },
  "servers": [
    {
      "url": "https://api.fetchlayer.dev/upwork"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Every error, on every route. Branch on code and retryable rather than on the text; on a 5xx the text is generic. MCP tool errors carry the same fields in structuredContent, and as a JSON text block.",
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in words. For a 400, what to change."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status, repeated in the body."
          },
          "code": {
            "type": "string",
            "description": "The kind of error, stable: invalid_input, unauthorized, insufficient_credits, forbidden, not_found, expired, quota_exceeded, cancelled, time_limit, temporarily_unavailable, posts_unavailable, store_unreachable, upstream_error, internal_error, tool_error. A platform may add its own; more may be added. Treat a code you do not recognise by its retryable flag."
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether asking again can succeed."
          },
          "requestId": {
            "type": "string",
            "description": "This request’s id, also sent as the X-Request-Id header. Quote it when reporting a problem."
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "With invalid_input when the request's parameters are refused before the request runs: the parameters that were missing. Always present on those errors, empty when nothing was missing."
          }
        },
        "required": [
          "error",
          "code",
          "retryable",
          "requestId"
        ]
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key."
      }
    }
  },
  "paths": {
    "/search-jobs": {
      "post": {
        "operationId": "search-jobs",
        "tags": [
          "Jobs"
        ],
        "summary": "Search job postings",
        "description": "Search public Upwork job postings by keyword or by an Upwork search page address, with the platform's own filters — job type, experience level, budget band, client history, location and posting age. Every field here is optional on its own, but the request carries a cross-field rule: **give either `query` or `searchUrl`**. An empty body is a 400 in about 80ms — `\"Provide either a query or a searchUrl.\"` — not an unfiltered search of everything. **Coverage caveat, and the first thing to build around.** A search always returns the listing-level fields Upwork puts on its results page. The fuller record behind each posting — the exact posting time, the proposal count, the client's hire history — is **not always available**, and what is available varies by hour. When it is not, this route still answers **200**: the postings carry listing-level fields only, `enrichedJobs` comes back **lower than `jobs.length`** (0 when nothing expanded), every job is marked `enriched: false`, and `notes[]` says so in words — *\"Full detail was not available for this request, so these postings carry listing-level fields only (see \\\"enriched\\\" on each job). Exact posting times, proposal counts and client hire history are omitted. Retrying often succeeds.\"* **Detect it with one comparison: `enrichedJobs` against `jobs.length`.** A thin row is a posting whose detail was not published to this request, not a posting with no proposals — reading it the second way silently corrupts any analysis built on it. Retrying often succeeds. Billing: 1 credit per results page fetched, reported as `pagesFetched`. A page costs the same whether it returns 3 postings or 50, and a posting that came back without its fuller record costs nothing extra.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Keywords to search postings for, e.g. \"python developer\". Either this or `searchUrl` must be given — an empty body is a 400."
                  },
                  "searchUrl": {
                    "type": "string",
                    "description": "An Upwork job-search page address to read the filters off, e.g. https://www.upwork.com/nx/search/jobs/?q=react. The easiest way to reproduce a search built in the Upwork UI. Either this or `query` must be given."
                  },
                  "page": {
                    "type": "integer",
                    "description": "Which results page to start from (1-1000).",
                    "example": "1"
                  },
                  "pages": {
                    "type": "integer",
                    "description": "How many results pages to walk, up to 20. Each page is 1 credit.",
                    "example": "1"
                  },
                  "perPage": {
                    "type": "integer",
                    "description": "Postings per page requested from Upwork, up to 50."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Maximum postings returned in total, up to 500."
                  },
                  "sort": {
                    "type": "string",
                    "description": "Result order: relevance or newest. Without it, the newest postings come first.",
                    "example": "newest"
                  },
                  "experienceLevel": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Narrow to these levels, any of: entry, intermediate, expert. For example [\"expert\"]."
                  },
                  "jobType": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Narrow to hourly and/or fixed postings. For example [\"hourly\"]."
                  },
                  "paymentVerified": {
                    "type": "boolean",
                    "description": "Only postings from clients whose payment method Upwork has verified."
                  },
                  "fixedPriceRange": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Fixed-price budget in USD as a [min, max] pair, e.g. [100, 1000]. Both non-negative, min no greater than max."
                  },
                  "hourlyRateRange": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Hourly rate in USD as a [min, max] pair, e.g. [20, 50]. Both non-negative, min no greater than max."
                  },
                  "clientHistory": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Narrow by how much the client has hired before, any of: noHires, 1to9Hires, 10+Hires."
                  },
                  "location": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Narrow to postings open to freelancers in these locations (up to 20). For example [\"United States\"]."
                  },
                  "maxJobAge": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Only postings newer than this age, as {value, unit} with unit one of minutes, hours, days, weeks. For example {\"value\": 24, \"unit\": \"hours\"}."
                  },
                  "filters": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "description": "Any further Upwork search filters (up to 20), as {key, operator, value} items using the search page's own field names. operator is one of includes, notIncludes, equals, notEquals, inRange."
                  },
                  "includeDetails": {
                    "type": "boolean",
                    "description": "Ask for every posting to come back with its fuller record. Best-effort: when it is not available, the response is still a 200 with listing-level fields, `enrichedJobs` below `jobs.length` and a note. Verified against prod — setting it true does not guarantee it."
                  },
                  "format": {
                    "type": "string",
                    "description": "json or markdown, in any case; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.",
                    "example": "json"
                  }
                },
                "additionalProperties": false
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "python developer",
                    "limit": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transport": {
                      "type": "string",
                      "description": "The data source: always the platform id, \"upwork\"."
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Caveats you can act on. The one that matters here says per-posting detail was not available and the postings carry listing-level fields only."
                    },
                    "pagesFetched": {
                      "type": "number",
                      "description": "Pages read, and what the request is billed at: 1 credit per page. A search of one results page is 1 whether it returns 3 postings or 50."
                    },
                    "query": {
                      "type": "string",
                      "description": "The keywords that were searched, or null when the request was made with `searchUrl` alone."
                    },
                    "searchUrl": {
                      "type": "string",
                      "description": "The Upwork results page the search read."
                    },
                    "pages": {
                      "type": "array",
                      "items": {
                        "type": "number"
                      },
                      "description": "Which results pages were walked."
                    },
                    "totalJobs": {
                      "type": "number",
                      "description": "How many postings came back."
                    },
                    "enrichedJobs": {
                      "type": "number",
                      "description": "**How many of them came back with their fuller record.** Compare this to `jobs.length`: lower means the rest carry listing-level fields only. This is the field to branch on, not `notes`."
                    },
                    "jobs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The posting's Upwork id, in its `~02…` form. Pass it to /job-detail as `jobId`."
                          },
                          "uid": {
                            "type": "string",
                            "description": "The same id without its prefix."
                          },
                          "title": {
                            "type": "string",
                            "description": "The posting title as published."
                          },
                          "description": {
                            "type": "string",
                            "description": "The posting body. On a listing this is the text Upwork shows on the results page."
                          },
                          "url": {
                            "type": "string",
                            "description": "The posting's full address. Pass it to /job-detail as `jobUrl`."
                          },
                          "jobType": {
                            "type": "string",
                            "description": "\"hourly\" or \"fixed\"."
                          },
                          "budget": {
                            "type": "object",
                            "additionalProperties": true,
                            "description": "Parsed rather than passed through as text: {type, amount, min, max, currency, raw}. A fixed-price posting fills `amount` ({type:\"fixed\", amount:210, currency:\"USD\", raw:\"Est. budget:$210.00\"}). An hourly posting with a published range fills `min` and `max` ({type:\"hourly\", min:15, max:100, currency:\"USD\", raw:\"Hourly: $15.00 - $100.00\"}). An hourly posting with no published range fills neither and keeps `raw: \"Hourly\"` — so a null `min` means Upwork published no rate, not that the rate is zero. `raw` is always the string Upwork showed, so any parse can be checked against it."
                          },
                          "experienceLevel": {
                            "type": "string",
                            "description": "The level the client asked for: entry, intermediate, expert (published capitalised, e.g. \"Intermediate\")."
                          },
                          "relativeDate": {
                            "type": "string",
                            "description": "The posting age exactly as Upwork wrote it, e.g. \"Posted 1 hour ago\"."
                          },
                          "postedAt": {
                            "type": "string",
                            "description": "An ISO timestamp. On an unenriched posting this is derived from `relativeDate`, so it is accurate to the bucket Upwork published rather than to the minute."
                          },
                          "postedAtIsApproximate": {
                            "type": "boolean",
                            "description": "True when `postedAt` came from the relative label rather than from an exact published time — which is the normal case on a listing. Check it before treating `postedAt` as a precise ordering key."
                          },
                          "skills": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "The skill tags on the posting, from Upwork's own annotations."
                          },
                          "proposals": {
                            "type": "number",
                            "description": "The exact proposal count. Published only on an expanded posting; null on a listing-level one."
                          },
                          "proposalsRange": {
                            "type": "object",
                            "additionalProperties": true,
                            "description": "{min, max, label} — the bucket Upwork shows on the results page, e.g. {min:50, max:null, label:\"50+\"}. This is what you get when `proposals` is null, and it is usually present even on an unenriched posting."
                          },
                          "duration": {
                            "type": "string",
                            "description": "Expected project length as published, e.g. \"1 to 3 months\"."
                          },
                          "workload": {
                            "type": "string",
                            "description": "Expected time commitment as published, e.g. \"Less than 30 hrs/week\"."
                          },
                          "freelancersToHire": {
                            "type": "number",
                            "description": "How many people the client intends to hire, when published. Also filled from the posting’s fuller record when the results page did not carry it."
                          },
                          "clientLocation": {
                            "type": "string",
                            "description": "The client's country as Upwork shows it."
                          },
                          "clientPaymentVerified": {
                            "type": "boolean",
                            "description": "Whether Upwork has verified the client's payment method."
                          },
                          "clientRating": {
                            "type": "number",
                            "description": "The client's average feedback score. 0 on a client with no history — check `clientFeedbackCount` before reading a 0 as a bad rating."
                          },
                          "clientFeedbackCount": {
                            "type": "number",
                            "description": "How many reviews that rating is based on."
                          },
                          "clientTotalSpent": {
                            "type": "number",
                            "description": "Total the client has spent on Upwork."
                          },
                          "clientHireRatePercent": {
                            "type": "number",
                            "description": "Share of the client's postings that ended in a hire. Published on an expanded posting."
                          },
                          "clientAvgHourlyRate": {
                            "type": "number",
                            "description": "Average hourly rate the client has paid. Published on an expanded posting."
                          },
                          "clientName": {
                            "type": "string",
                            "description": "The client name, where one could be established."
                          },
                          "clientNameConfidence": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "How firmly `clientName` was established, from 0 to 0.99, so a guess is never mistaken for a published name. Null when no name was found."
                          },
                          "clientHasHired": {
                            "type": "boolean",
                            "description": "Whether the client has hired before. Published on an expanded posting."
                          },
                          "allowedApplicantCountries": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Countries the client restricted applicants to, when they did."
                          },
                          "screeningQuestions": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Questions applicants must answer, when the posting has any."
                          },
                          "category": {
                            "type": "string",
                            "description": "Upwork's category for the posting."
                          },
                          "categoryGroup": {
                            "type": "string",
                            "description": "Upwork's broader category group."
                          },
                          "specialty": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The posting’s specialty within its category, for example \"DevOps Engineering\". Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "durationWeeks": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "The duration bucket in weeks, alongside the `duration` label. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "interviewing": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "Freelancers invited to interview. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "invitesSent": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "Invitations the client sent. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "unansweredInvites": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "Invitations not answered yet. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "hiredCount": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "Freelancers hired on this posting so far. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "clientLastActivity": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "ISO 8601 time of the client’s last activity on this posting. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "clientCity": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The client’s city. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "clientTimezone": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The client’s time zone, for example \"America/New_York (UTC-05:00)\". Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "clientMemberSince": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "ISO 8601 time the client joined Upwork. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "clientJobsPosted": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "How many postings the client has made. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "clientOpenJobs": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "The client’s postings open now. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "clientHires": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "The client’s past postings that ended in a hire. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "clientTotalHours": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Hours billed to the client. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "clientActiveContracts": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "The client’s active contracts. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "clientIndustry": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The client’s industry. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "requiredJobSuccessScore": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "The minimum Job Success Score applicants must have; null when none is asked. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "requiredEnglishLevel": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The English level applicants must have: \"Basic\", \"Conversational\", \"Fluent\" or \"Native or bilingual\"; null when any level is accepted. Null on a posting that is not enriched, and when Upwork does not say."
                          },
                          "enriched": {
                            "type": "boolean",
                            "description": "Whether this posting came back with its fuller record. **False is the field to branch on**: it means the fields above marked \"published on an expanded posting\" are absent for this row, and it is not an error."
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "query": "python developer",
                      "searchUrl": "https://www.upwork.com/nx/search/jobs/?q=python+developer",
                      "pages": [
                        1
                      ],
                      "totalJobs": 5,
                      "enrichedJobs": 0,
                      "jobs": [
                        {
                          "id": "~022100333565184435123",
                          "uid": "2100333565184435123",
                          "title": "Full Stack Developer for Web App",
                          "description": "We need a full stack developer to build a web app for a small business. …",
                          "url": "https://www.upwork.com/jobs/Full-Stack-Developer-for-Web-App_~022100333565184435123/",
                          "jobType": "hourly",
                          "budget": {
                            "type": "hourly",
                            "amount": null,
                            "min": 15,
                            "max": 100,
                            "currency": "USD",
                            "raw": "Hourly: $15.00 - $100.00"
                          },
                          "experienceLevel": "Intermediate",
                          "relativeDate": "Posted 1 hour ago",
                          "postedAt": "2026-09-16T21:52:00.000Z",
                          "postedAtIsApproximate": true,
                          "skills": [
                            "Python",
                            "JavaScript",
                            "HTML5",
                            "PHP",
                            "AngularJS",
                            "TypeScript"
                          ],
                          "proposals": null,
                          "proposalsRange": {
                            "min": 50,
                            "max": null,
                            "label": "50+"
                          },
                          "duration": "1 to 3 months",
                          "workload": "Less than 30 hrs/week",
                          "clientLocation": "United States",
                          "clientPaymentVerified": true,
                          "clientRating": 0,
                          "clientFeedbackCount": 0,
                          "clientTotalSpent": 0,
                          "enriched": false
                        },
                        {
                          "id": "~022100291793583666591",
                          "uid": "2100291793583666591",
                          "title": "Digital Skills Teacher",
                          "description": "…",
                          "url": "https://www.upwork.com/jobs/Digital-Skills-Teacher_~022100291793583666591/",
                          "jobType": "fixed",
                          "budget": {
                            "type": "fixed",
                            "amount": 210,
                            "min": null,
                            "max": null,
                            "currency": "USD",
                            "raw": "Est. budget:$210.00"
                          },
                          "experienceLevel": "Intermediate",
                          "relativeDate": "Posted 2 hours ago",
                          "postedAt": "2026-09-16T20:52:00.000Z",
                          "postedAtIsApproximate": true,
                          "skills": [
                            "Teaching",
                            "Curriculum Development"
                          ],
                          "proposals": null,
                          "proposalsRange": {
                            "min": 10,
                            "max": 15,
                            "label": "10 to 15"
                          },
                          "clientLocation": "United Kingdom",
                          "clientPaymentVerified": true,
                          "enriched": false
                        }
                      ],
                      "notes": [
                        "Full detail was not available for this request, so these postings carry listing-level fields only (see \"enriched\" on each job). Exact posting times, proposal counts and client hire history are omitted. Retrying often succeeds."
                      ],
                      "transport": "upwork",
                      "pagesFetched": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/job-detail": {
      "post": {
        "operationId": "job-detail",
        "tags": [
          "Jobs"
        ],
        "summary": "Read one posting in full",
        "description": "Read one Upwork posting in full by its id or its URL — the fuller record behind a search result, with the exact posting time, the proposal count and the client's hire history. Give either `jobId` or `jobUrl`; an empty body is a 400 saying `\"Provide either a jobId or a jobUrl.\"` **Coverage caveat, and the first thing to build around.** A search always returns the listing-level fields Upwork puts on its results page. The fuller record behind each posting — the exact posting time, the proposal count, the client's hire history — is **not always available**, and what is available varies by hour. When it is not, this route still answers **200**: the postings carry listing-level fields only, `enrichedJobs` comes back **lower than `jobs.length`** (0 when nothing expanded), every job is marked `enriched: false`, and `notes[]` says so in words — *\"Full detail was not available for this request, so these postings carry listing-level fields only (see \\\"enriched\\\" on each job). Exact posting times, proposal counts and client hire history are omitted. Retrying often succeeds.\"* **Detect it with one comparison: `enrichedJobs` against `jobs.length`.** A thin row is a posting whose detail was not published to this request, not a posting with no proposals — reading it the second way silently corrupts any analysis built on it. Retrying often succeeds. **Here the same gap is a 503, not a thin 200**, because this route returns only that fuller record and has no listing-level rows to hand back instead: `{\"error\":\"The upstream source is temporarily refusing automated requests. Please retry.\"}`. Four consecutive calls returned it during the window measured on 17 September 2026, while `/search-jobs` kept answering 200 throughout. Treat this route as best-effort: retry it, and fall back to the listing-level fields from a search when you need breadth rather than depth. Billing: 1 credit per page fetched, reported as `pagesFetched`. A 503 fetched no page.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jobId": {
                    "type": "string",
                    "description": "The posting's id, as returned on a search result's `id` or `uid`. Either this or `jobUrl` must be given."
                  },
                  "jobUrl": {
                    "type": "string",
                    "description": "The posting's full Upwork address, as returned on a search result's `url`. Either this or `jobId` must be given."
                  },
                  "format": {
                    "type": "string",
                    "description": "json or markdown, in any case; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.",
                    "example": "json"
                  }
                },
                "additionalProperties": false
              },
              "examples": {
                "default": {
                  "value": {
                    "jobUrl": "https://www.upwork.com/jobs/Digital-Skills-Teacher_~022100291793583666591/"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transport": {
                      "type": "string",
                      "description": "The data source: always the platform id, \"upwork\"."
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Caveats you can act on. The one that matters here says per-posting detail was not available and the postings carry listing-level fields only."
                    },
                    "pagesFetched": {
                      "type": "number",
                      "description": "Pages read, and what the request is billed at: 1 credit per page. A search of one results page is 1 whether it returns 3 postings or 50."
                    },
                    "job": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "The posting, in the same shape as a `jobs[]` entry from /search-jobs — with `enriched: true` and the fuller fields filled in."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "error": "The upstream source is temporarily refusing automated requests. Please retry."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/resolve-url": {
      "post": {
        "operationId": "resolve-url",
        "tags": [
          "Utilities"
        ],
        "summary": "Parse an Upwork address",
        "description": "Parse any Upwork address into structured input for the other routes, without fetching anything. Tells you whether an address is a results page or a posting, and pulls the search terms off a results page so you can hand them straight to /search-jobs. The right first step for a list of pasted addresses — it sorts them before a single page fetch is spent. **Free.** It makes no upstream request at all, answers in about a tenth of a second, and reports `pagesFetched: 0`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Any Upwork address — a job posting or a job-search results page."
                  },
                  "format": {
                    "type": "string",
                    "description": "json or markdown, in any case; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.",
                    "example": "json"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "url"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "url": "https://www.upwork.com/nx/search/jobs/?q=python"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transport": {
                      "type": "string",
                      "description": "The data source: always the platform id, \"upwork\"."
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Caveats you can act on. The one that matters here says per-posting detail was not available and the postings carry listing-level fields only."
                    },
                    "pagesFetched": {
                      "type": "number",
                      "description": "Pages read, and what the request is billed at: 1 credit per page. A search of one results page is 1 whether it returns 3 postings or 50."
                    },
                    "kind": {
                      "type": "string",
                      "description": "\"search\" for a results page, or the posting kind for a single job."
                    },
                    "jobId": {
                      "type": "string",
                      "description": "The posting's id when the address names one; null on a results page."
                    },
                    "searchUrl": {
                      "type": "string",
                      "description": "The results page address, ready to pass to /search-jobs as `searchUrl`."
                    },
                    "query": {
                      "type": "string",
                      "description": "The search terms read off a results page, ready to pass to /search-jobs as `query`."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "kind": "search",
                      "jobId": null,
                      "searchUrl": "https://www.upwork.com/nx/search/jobs/?q=python",
                      "query": "python",
                      "notes": [
                        "Use the job search capability with this searchUrl."
                      ],
                      "transport": "upwork",
                      "pagesFetched": 0
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}