---
title: "Resolve a config"
method: POST
path: "/config-registry/resolve"
tags: ["Config Registry"]
---

# Resolve a config

`POST /config-registry/resolve`

## Request

- Base URL: `https://api.onkernel.com`
- URL: `https://api.onkernel.com/config-registry/resolve`
- Auth: HTTP bearer

Explicitly starts or retries a project-scoped background analysis while preserving current global knowledge when available. Use `/config-registry/lookup` for side-effect-free reads.

## Request body

- ConfigRegistryResolveRequest
  - `allowed_proxy_countries` string[]: ISO 3166 country codes Kernel may use when searching for or returning a proxy configuration. Kernel may test a subset of allowed countries. When omitted, Kernel uses its default country selection.
  - `intent` string: Plain-language description of the workload you intend to run against this target, in a sentence or two. Requires an https target, because the pass treats any non-HTTPS destination as off-site and will not drive an http one. Kernel uses it to drive the browser further into the site, where it can observe protections that only appear once a session interacts. When this target already has a recommended configuration, the run confirms that one instead of re-deriving the whole matrix, so supplying an intent narrows what can be recommended.
  - `url` string, uri, required: Public HTTP(S) URL to refresh.

## Response `200`

Current recommendation returned. Analysis is null if DNS validation or workflow submission prevented the requested refresh.

- ConfigRegistryResponse
  - `analysis` ConfigRegistryAnalysis, required
    - `created_at` string, date-time, required: Time the analysis was created.
    - `expires_at` string, date-time, required: Deadline after which a still-running analysis becomes expired.
    - `failure` Error, required
      - `code` string, required: Application-specific error code (machine-readable)
      - `details` ErrorDetail[]: Additional error details (for multiple errors)
        - `code` string: Lower-level error code providing more specific detail
        - `message` string: Further detail about the error
      - `inner_error` ErrorDetail
        - `code` string: Lower-level error code providing more specific detail
        - `message` string: Further detail about the error
      - `message` string, required: Human-readable error description for debugging
    - `finished_at` string, date-time, nullable, required: Time the analysis reached a terminal status. Null while it is running.
    - `id` string, required: Discovery run ID used to poll analysis status.
    - `intent` string, nullable: The workload description supplied for this analysis. Null when the analysis only tested connectivity.
    - `status` 'running' | 'completed' | 'failed' | 'canceled' | 'expired', required: Lifecycle status of a background analysis.
  - `guidance` string, nullable: Short advisory markdown to facilitate navigating this target. Returned even when no configuration reached the target, since knowing what prevented success is useful without a configuration. Not verified against this target. Null when nothing applicable was observed or no notes exist.
  - `recommendation` union, required: A recommendation or a structured no-recommendation result.
    - ConfigRegistryRecommendation
      - `browser` ConfigRegistryBrowser, required: Browser settings that can be passed directly to `POST /browsers`.
        - `gpu` boolean, required
        - `headless` boolean, required
        - `stealth` boolean, required
        - `viewport` BrowserViewport, required: Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). For GPU images, the default is 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60, 768x1024@60, 390x844@60. For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10: 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep bandwidth reasonable).
          - `height` integer, required: Browser window height in pixels. Any positive integer is accepted.
          - `refresh_rate` integer: Display refresh rate in Hz. Any positive integer is accepted; if omitted, GPU browsers default to 60 and other browsers derive it from width and height.
          - `width` integer, required: Browser window width in pixels. Any positive integer is accepted.
      - `evidence` ConfigRegistryEvidence, required
        - `accessed` integer, required
        - `blocked` integer, required
        - `inconclusive` integer, required
        - `last_observed_at` string, date-time, required: Most recent contributing observation. Recommendations remain eligible regardless of age and can be returned while a new analysis refreshes them.
        - `last_supported_at` string, date-time, nullable: Most recent contributing run whose evidence supported recommending this configuration. Omitted when no individual run independently met the recommendation threshold.
        - `run_count` integer, required
        - `sample_size` integer, required: Number of judged trials.
        - `success_rate` number, required: Accessed trials divided by judged trials. Inconclusive trials are excluded.
      - `match_scope` 'exact' | 'host' | 'domain', required: Specificity of knowledge matched for this recommendation. Exact matches use knowledge for the requested target; host and domain matches use broader fallback knowledge.
      - `matched_target` string, required: Target value that supplied the recommendation.
      - `proxy` union, required: Proxy recipe for the recommended browser.
        - ConfigRegistryDirectProxy: Direct egress recipe. Pass `{ "mode": "direct" }` as the browser's `proxy`.
          - `mode` 'direct', required
        - ConfigRegistryManagedProxy: Managed proxy recipe. `create` is a non-idempotent `POST /proxies` payload: create the resource once, retain its ID, and reuse that ID as the browser's `proxy.id`. Do not submit this recipe before every browser session.
          - `create` ProxyCreateRequest, required: Configuration for routing traffic through a proxy.
            - `bypass_hosts` string[]: Hostnames that should bypass the parent proxy and connect directly.
            - `config` union: Configuration specific to the selected proxy `type`.
              - …
            - `name` string: Readable name of the proxy.
            - `protocol` 'http' | 'https': Protocol to use for the proxy connection.
            - `type` 'datacenter' | 'isp' | 'residential' | 'mobile' | 'custom', required: Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp`. `datacenter` is deprecated; use `isp` instead. Datacenter proxy creation remains supported for backward compatibility.
          - `mode` 'managed', required
      - `type` 'recommendation', required
    - ConfigRegistryNoRecommendation
      - `code` 'proxy_restricted' | 'target_not_evaluable' | 'no_working_configuration' | 'inconclusive', required: Machine-readable reason Kernel cannot currently provide a config recommendation.
      - `message` string, required: Human-readable explanation suitable for display.
      - `type` 'no_recommendation', required
  - `target` ConfigRegistryTarget, required
    - `domain` string, required: Registrable domain.
    - `host` string, required: Full hostname, including subdomain.
    - `normalized` string, required: Exact normalized scheme, host, port, and path used for lookup.
  - `working_configurations` ConfigRegistryRecommendation[], required: Working configurations for the target, ordered with the recommended configuration first.
    - `browser` ConfigRegistryBrowser, required: Browser settings that can be passed directly to `POST /browsers`.
      - `gpu` boolean, required
      - `headless` boolean, required
      - `stealth` boolean, required
      - `viewport` BrowserViewport, required: Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). For GPU images, the default is 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60, 768x1024@60, 390x844@60. For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10: 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep bandwidth reasonable).
        - `height` integer, required: Browser window height in pixels. Any positive integer is accepted.
        - `refresh_rate` integer: Display refresh rate in Hz. Any positive integer is accepted; if omitted, GPU browsers default to 60 and other browsers derive it from width and height.
        - `width` integer, required: Browser window width in pixels. Any positive integer is accepted.
    - `evidence` ConfigRegistryEvidence, required
      - `accessed` integer, required
      - `blocked` integer, required
      - `inconclusive` integer, required
      - `last_observed_at` string, date-time, required: Most recent contributing observation. Recommendations remain eligible regardless of age and can be returned while a new analysis refreshes them.
      - `last_supported_at` string, date-time, nullable: Most recent contributing run whose evidence supported recommending this configuration. Omitted when no individual run independently met the recommendation threshold.
      - `run_count` integer, required
      - `sample_size` integer, required: Number of judged trials.
      - `success_rate` number, required: Accessed trials divided by judged trials. Inconclusive trials are excluded.
    - `match_scope` 'exact' | 'host' | 'domain', required: Specificity of knowledge matched for this recommendation. Exact matches use knowledge for the requested target; host and domain matches use broader fallback knowledge.
    - `matched_target` string, required: Target value that supplied the recommendation.
    - `proxy` union, required: Proxy recipe for the recommended browser.
      - ConfigRegistryDirectProxy: Direct egress recipe. Pass `{ "mode": "direct" }` as the browser's `proxy`.
        - `mode` 'direct', required
      - ConfigRegistryManagedProxy: Managed proxy recipe. `create` is a non-idempotent `POST /proxies` payload: create the resource once, retain its ID, and reuse that ID as the browser's `proxy.id`. Do not submit this recipe before every browser session.
        - `create` ProxyCreateRequest, required: Configuration for routing traffic through a proxy.
          - `bypass_hosts` string[]: Hostnames that should bypass the parent proxy and connect directly.
          - `config` union: Configuration specific to the selected proxy `type`.
            - object: Configuration for a deprecated datacenter proxy. Use an ISP proxy instead.
              - …
            - object: Configuration for an ISP proxy.
              - …
            - object: Configuration for residential proxies.
              - …
            - object: Configuration for mobile proxies.
              - …
            - object: Configuration for a custom proxy (e.g., private proxy server).
              - …
          - `name` string: Readable name of the proxy.
          - `protocol` 'http' | 'https': Protocol to use for the proxy connection.
          - `type` 'datacenter' | 'isp' | 'residential' | 'mobile' | 'custom', required: Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp`. `datacenter` is deprecated; use `isp` instead. Datacenter proxy creation remains supported for backward compatibility.
        - `mode` 'managed', required
    - `type` 'recommendation', required
  - `workload_outcome` 'completed' | 'turn_limit' | 'auth_required' | 'payment_required' | 'blocked' | 'error', nullable: How far the workload pass got, when an intent was supplied and a pass ran. A run outcome rather than advice, so it is reported whether or not any guidance could be assembled. Null when no intent was supplied or no pass ran.

## Other responses

- `202`: Analysis is running without a current recommendation.
- `400`: Bad Request – invalid input
- `401`: Unauthorized – missing or invalid authorization token
- `403`: Forbidden – insufficient permissions or plan
- `404`: Resource not found
- `409`: An analysis for this target is already running with a different workload intent. Poll the returned analysis ID and retry once it reaches a terminal status.
- `429`: Too Many Requests – rate limit exceeded
- `500`: Internal Server Error
- `503`: Analysis could not be submitted.

## Changes

- **2026-10-16** `03b369edee49`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kernel/apis/kernel-api/changes/config-registry/resolve/post.md)

---

[API](https://skmtc.dev/kernel/apis/kernel-api.md) - [All operations](https://skmtc.dev/kernel/apis/kernel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kernel/apis/kernel-api/revisions/0f6cf4f58fe6?raw)