> ## Documentation Index > Fetch the complete documentation index at: https://docs.valendata.com/llms.txt > Use this file to discover all available pages before exploring further. # Find a skill for a task > Skills or workflows that do a task, best first, from the public marketplace and your own, each with its price per run and track record. Put the task in `q`, in plain words, for example `find LinkedIn jobs in Toronto`. Matching reads the meaning of `q`, not only its words. A query that names a site, such as `linkedin`, lifts that site's skills; a skill on another site is then only a near match. Narrow the search with `site` (only skills for this website, for example `linkedin.com`) and `category`. `limit` is 1–50, default 10. `kind` picks what to search: `skill` (the default) or `workflow`. See [Workflows](#workflows). Results are ranked by how well they match, weighed by health (success rate over the last 20 runs, and a recent success) and a little by use. | Field | What it is | | - | - | | `kind` | `skill` or `workflow`, as you searched. | | `slug`, `name`, `description`, `site`, `category` | The skill, and the website it works on. | | `official` | `true` for an official Valendata skill. | | `yours` | `true` for your own skill, or one shared into your workspace. | | `inputs` | Each input's `name`, `type`, and `required`. For the full contract, call [Get a skill](/api-reference/skills/get). | | `price` | What a run usually costs, in credits and dollars. See [Price](/api-reference/skills/get#price). | | `health` | `success_rate_20` (percent of the last 20 runs that worked), `last_success_at`, and `total_runs`. | | `sample_rows` | Up to 3 rows the skill returned when it was published, so you can see what it returns. | | `match` | `strong`: it does this task. `near`: the closest there is. | | `score` | How well it matches, weighed by health. Higher is better. | | `run_url`, `info_url` | The routes to [run it](/api-reference/runs/run-skill) and to [read its contract](/api-reference/skills/get). | | `clone_url` | The route to [clone it](/api-reference/skills/clone) into your own skills. `null` when `yours` is `true`. | When no skill does the task, up to 3 of the closest come back with `match: "near"`, and `hint` says so. You can then record exactly this task with [Create a skill](/api-reference/skills/create). Otherwise `hint` is `null`. Searching the public marketplace needs no key. With a key or session that holds `skills:read`, your own skills and your workspaces' are searched too. A key without `skills:read` searches the marketplace only. A bad key is still a `401`. A skill that is not yours runs only after you clone it. Running it directly returns `403` `clone_required`. See [Errors](/api-reference/errors#error-body). MCP tool: `search_skills`. ## Workflows With `kind=workflow`, the results are workflows, in the same shape: * `inputs`, `price`, `sample_rows`, `match`, and `score` work as for skills. `price` is the typical cost of its last 20 completed runs, or its base fee before any. Sample rows hold no secret fields, and long values are cut short. * `health` has `total_runs` only. * `site` and `official` are not used. The `site` filter does not apply. * `run_url` is [Run a workflow and wait](/api-reference/runs/run-workflow), `info_url` is [Get a workflow](/api-reference/workflows/get), and `clone_url` is [Clone a workflow](/api-reference/workflows/clone). `clone_url` is `null` when `yours` is `true`. A workflow that is not yours answers `404` to a run until you clone it. With a key or session that holds `workflows:read`, your own workflows and your workspaces' are searched too. When no workflow does the task, the closest come back with `match: "near"`, and `hint` points to [Create a workflow](/api-reference/workflows/create). MCP tool: `search_workflows`. ## OpenAPI ````yaml GET /v1/marketplace/search openapi: 3.1.0 info: title: Valendata REST API version: 1.0.0 description: >- Create, run, schedule, and improve skills and workflows over JSON and HTTPS. Every route is under `/v1`; changes inside v1 are additive only (new routes, new optional parameters, new response fields). A route that will go away is marked `deprecated` here and answers with `Deprecation`, `Sunset` and a `Link` to its replacement for at least six months before it is removed. Errors, limits, pagination and idempotency: https://docs.valendata.com/api-reference/errors. license: name: Proprietary url: https://www.valendata.com/terms-and-conditions servers: - url: https://api.valendata.com description: Production security: - ApiKeyAuth: [] - ApiKeyHeader: [] tags: - name: Skills description: List, create, read, update, and delete skills. - name: Marketplace description: Find a skill by the task, with its price per run and track record. - name: Runs description: Run skills and workflows, read any run, and cancel one. - name: Skill versions description: List, compare, restore, and pin a skill's versions. - name: Improvements description: >- Fix a skill, add fields, or re-learn its detail steps, and read its change history. - name: Schedules description: Run a skill or workflow on a fixed cadence. - name: Workflows description: List, create, read, update, and delete workflows. - name: Logins description: Saved website logins a skill can sign in with. - name: Account and usage description: Your plan, credit balance, and usage. - name: Webhooks description: The secret that signs webhook deliveries. paths: /v1/marketplace/search: get: tags: - Marketplace summary: Find a skill for a task description: >- Skills that do the task in `q`, best first, from the public marketplace and (with `skills:read`) your own and your workspaces' (`yours: true`). Each result has its inputs, `price` (the typical cost of its recent runs in credits and dollars, or its base price before any run), `health` (success rate over its last 20 runs) and the route to run it. Matching reads the meaning of `q`, not only its words. When nothing does the task, the closest skills come back with `match: "near"` and a `hint`. No key needed for the public marketplace. operationId: search_skills parameters: - name: q in: query required: true schema: type: string minLength: 2 maxLength: 300 description: 'The task, in your words: ''find LinkedIn jobs in Toronto''' title: Q description: 'The task, in your words: ''find LinkedIn jobs in Toronto''' - name: site in: query required: false schema: anyOf: - type: string maxLength: 200 - type: 'null' description: Only skills for this website, e.g. linkedin.com title: Site description: Only skills for this website, e.g. linkedin.com - name: category in: query required: false schema: anyOf: - type: string maxLength: 100 - type: 'null' title: Category - name: limit in: query required: false schema: type: integer maximum: 50 minimum: 1 default: 10 title: Limit description: Most results to return, 1–50. - name: kind in: query required: false schema: enum: - skill - workflow type: string description: Search skills or workflows default: skill title: Kind description: Search skills or workflows responses: '200': description: Skills that do the task, best first. content: application/json: schema: $ref: '#/components/schemas/SkillSearchResponse' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] - ApiKeyHeader: [] - {} components: schemas: SkillSearchResponse: properties: query: type: string title: Query results: items: $ref: '#/components/schemas/SkillSearchHit' type: array title: Results hint: anyOf: - type: string - type: 'null' title: Hint description: What to do when nothing does this task exactly type: object required: - query - results title: SkillSearchResponse SkillSearchHit: properties: kind: type: string enum: - skill - workflow title: Kind description: What the result is default: skill slug: type: string title: Slug name: type: string title: Name description: anyOf: - type: string - type: 'null' title: Description site: anyOf: - type: string - type: 'null' title: Site description: The website the skill works on category: anyOf: - type: string - type: 'null' title: Category official: type: boolean title: Official default: false yours: type: boolean title: Yours description: Your own skill, or one shared into your workspace default: false inputs: items: $ref: '#/components/schemas/SearchInput' type: array title: Inputs price: $ref: '#/components/schemas/SkillPrice' health: $ref: '#/components/schemas/SearchHealth' sample_rows: items: additionalProperties: true type: object type: array title: Sample Rows description: >- A few rows the skill returned when it was published — what it returns match: type: string enum: - strong - near title: Match description: 'strong: does this task; near: the closest there is' score: type: number title: Score description: Relevance, health-weighted (higher is better) run_url: type: string title: Run Url description: >- Where to run it — a skill that is not yours runs once you clone it (clone_url) clone_url: anyOf: - type: string - type: 'null' title: Clone Url description: Clone a skill that is not yours here first, then run the copy info_url: type: string title: Info Url type: object required: - slug - name - price - health - match - score - run_url - info_url title: SkillSearchHit Error: type: object required: - detail - code - type - request_id properties: detail: description: What went wrong. A string, or an object for errors with more to say. oneOf: - type: string - additionalProperties: true type: object code: type: string description: >- Stable machine-readable code. Known values: `bad_request`, `invalid_json`, `invalid_cursor`, `invalid_idempotency_key`, `unauthorized`, `payment_required`, `permission_denied`, `not_found`, `method_not_allowed`, `conflict`, `idempotency_key_in_use`, `idempotent_replay_unavailable`, `payload_too_large`, `unsupported_media_type`, `validation_error`, `idempotency_key_reused`, `rate_limited`, `internal_error`, `upstream_error`, `service_unavailable`. example: not_found type: type: string enum: - invalid_request_error - authentication_error - billing_error - permission_error - conflict_error - idempotency_error - rate_limit_error - api_error description: The broad category of the error. request_id: type: string description: Also in the `X-Request-ID` header. example: 3f9a1c2b7d4e param: type: string description: >- The field at fault, on validation errors (dotted path, e.g. `inputs.city`). errors: type: array items: additionalProperties: true type: object description: Every validation problem, on a 422 from request validation. SearchInput: properties: name: type: string title: Name type: type: string title: Type default: string required: type: boolean title: Required default: false type: object required: - name title: SearchInput SkillPrice: properties: estimate_credits: type: number title: Estimate Credits description: >- Credits a run usually costs — the typical recent run, else the base price estimate_usd: type: number title: Estimate Usd description: estimate_credits in US dollars base_credits: type: integer title: Base Credits description: The least a run costs (its base fee) typical_credits: anyOf: - type: number - type: 'null' title: Typical Credits description: Median cost of the recent successful runs; null before any recent_runs: type: integer title: Recent Runs description: How many recent successful runs the typical cost is read from default: 0 basis: type: string enum: - typical_of_recent_runs - base_price title: Basis description: Where estimate_credits comes from type: object required: - estimate_credits - estimate_usd - base_credits - basis title: SkillPrice description: What one run of the skill costs, before it runs. SearchHealth: properties: success_rate_20: anyOf: - type: number - type: 'null' title: Success Rate 20 description: Percent of the last 20 runs that worked last_success_at: anyOf: - type: string format: date-time - type: 'null' title: Last Success At total_runs: type: integer title: Total Runs default: 0 type: object title: SearchHealth headers: X-Request-ID: description: >- This request's id (yours, if you sent a valid `X-Request-ID`). Quote it to support. schema: type: string X-RateLimit-Limit: description: Requests a minute this API key may make. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current minute. schema: type: integer X-RateLimit-Reset: description: Unix time (seconds) the current window ends. schema: type: integer Retry-After: description: Seconds to wait before retrying. schema: type: integer responses: Unauthorized: description: The API key is missing, malformed, revoked, or expired. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: The API key is missing, malformed, revoked, or expired. code: unauthorized type: authentication_error request_id: 3f9a1c2b7d4e Unprocessable: description: >- A field is invalid (`param` names it), or the Idempotency-Key was used with a different request. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: 'Invalid request — name: Field required' code: validation_error type: invalid_request_error request_id: 3f9a1c2b7d4e param: name errors: - type: missing loc: - body - name msg: Field required RateLimited: description: >- Too many requests for this key, or too many runs in progress. Wait `Retry-After` seconds. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: >- Too many requests for this key, or too many runs in progress. Wait `Retry-After` seconds. code: rate_limited type: rate_limit_error request_id: 3f9a1c2b7d4e InternalError: description: >- Something broke on our side. Retry; runs that fail on our side are refunded. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: >- Something broke on our side. Retry; runs that fail on our side are refunded. code: internal_error type: api_error request_id: 3f9a1c2b7d4e securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: vd_sk_... description: >- API key with the `vd_sk_` prefix, as `Authorization: Bearer vd_sk_...`. Create keys in Settings → API Keys. ApiKeyHeader: type: apiKey in: header name: x-api-key description: The same API key in the `x-api-key` header. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.