# Harness Support
Internal operations for agent harnesses managed by Oz
## Create external conversation
> Create a new external conversation record for a harness. Returns a conversation ID\
> for bookkeeping.\
> \
> This may only be called from within a cloud agent execution environment.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"harness-support","description":"Internal operations for agent harnesses managed by Oz"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"CreateExternalConversationRequest":{"type":"object","description":"Request body for creating a new external conversation for a third-party harness.","required":["format"],"properties":{"format":{"type":"string","description":"The conversation format identifying the harness type.\n"}}},"CreateExternalConversationResponse":{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"type":"string","description":"The unique identifier of the newly created conversation."}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/harness-support/external-conversation":{"post":{"summary":"Create external conversation","description":"Create a new external conversation record for a harness. Returns a conversation ID\nfor bookkeeping.\n\nThis may only be called from within a cloud agent execution environment.\n","operationId":"createExternalConversation","tags":["harness-support"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExternalConversationRequest"}}}},"responses":{"200":{"description":"External conversation created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExternalConversationResponse"}}}},"400":{"description":"Invalid request (missing or unsupported format)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No permission to modify the task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Report an artifact
> Report an artifact (e.g., a pull request) created by a third-party harness back to\
> the Oz platform. The artifact is associated with the current task's conversation.\
> \
> This may only be called from within a cloud agent execution environment.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"harness-support","description":"Internal operations for agent harnesses managed by Oz"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"ReportArtifactRequest":{"oneOf":[{"$ref":"#/components/schemas/ReportPullRequestArtifactRequest"}],"discriminator":{"propertyName":"artifact_type","mapping":{"PULL_REQUEST":"#/components/schemas/ReportPullRequestArtifactRequest"}}},"ReportPullRequestArtifactRequest":{"type":"object","description":"Request body for reporting a pull request artifact.","required":["artifact_type","data"],"properties":{"artifact_type":{"type":"string","enum":["PULL_REQUEST"],"description":"Type of artifact being reported."},"data":{"$ref":"#/components/schemas/PullRequestArtifactData"}}},"PullRequestArtifactData":{"type":"object","required":["url","branch"],"properties":{"url":{"type":"string","format":"uri","description":"URL of the pull request"},"branch":{"type":"string","description":"Branch name for the pull request"}}},"ReportArtifactResponse":{"type":"object","required":["artifact_uid"],"properties":{"artifact_uid":{"type":"string","description":"Unique identifier for the created artifact"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/harness-support/report-artifact":{"post":{"summary":"Report an artifact","description":"Report an artifact (e.g., a pull request) created by a third-party harness back to\nthe Oz platform. The artifact is associated with the current task's conversation.\n\nThis may only be called from within a cloud agent execution environment.\n","operationId":"reportArtifact","tags":["harness-support"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportArtifactRequest"}}}},"responses":{"200":{"description":"Artifact reported successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportArtifactResponse"}}}},"400":{"description":"Invalid request (missing or unsupported artifact type)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No permission to modify the task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Resolve effective prompt
> Resolve the effective prompt for the current task, including optional skill content\
> and attachment references. This may only be called from within a cloud agent execution\
> environment.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"harness-support","description":"Internal operations for agent harnesses managed by Oz"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"ResolvePromptRequest":{"type":"object","description":"Request body for resolving the effective prompt for a task.","properties":{"skill":{"type":"object","description":"Optional skill metadata to prepend to the prompt.","required":["name","content"],"properties":{"name":{"type":"string","description":"Human-readable name of the skill"},"content":{"type":"string","description":"The resolved skill content"},"path":{"type":"string","description":"Full path to SKILL.md (optional)"}}},"attachments_dir":{"type":"string","description":"Directory where attachments were downloaded locally"}}},"ResolvePromptResponse":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"The resolved prompt"},"system_prompt":{"type":"string","description":"Optional system prompt addition for the harness"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/harness-support/resolve-prompt":{"post":{"summary":"Resolve effective prompt","description":"Resolve the effective prompt for the current task, including optional skill content\nand attachment references. This may only be called from within a cloud agent execution\nenvironment.\n","operationId":"resolvePrompt","tags":["harness-support"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvePromptRequest"}}}},"responses":{"200":{"description":"Resolved prompt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvePromptResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No permission to access the task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Prepare upload of a conversation transcript
> Allocates and returns a storage slot for uploading the raw conversation transcript.\
> The caller should make an HTTP request to the target with the transcript contents\
> as the request body.\
> \
> This may only be called from within a cloud agent execution environment.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"harness-support","description":"Internal operations for agent harnesses managed by Oz"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"GetUploadTargetRequest":{"type":"object","description":"Request body for obtaining a conversation-scoped upload target.","required":["conversation_id"],"properties":{"conversation_id":{"type":"string","description":"The conversation ID to associate the uploaded data with."}}},"UploadTarget":{"type":"object","description":"A description of where and how to upload a blob.\nUse the `method` and `url` to upload, including all `headers` in the request.\nPass the blob to upload as the request body.\n","required":["url","method","headers"],"properties":{"url":{"type":"string","format":"uri","description":"The presigned URL to upload the blob to."},"method":{"type":"string","enum":["PUT","POST"],"description":"The HTTP method to use for the upload."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"HTTP headers that must be included in the upload request."}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/harness-support/transcript":{"post":{"summary":"Prepare upload of a conversation transcript","description":"Allocates and returns a storage slot for uploading the raw conversation transcript.\nThe caller should make an HTTP request to the target with the transcript contents\nas the request body.\n\nThis may only be called from within a cloud agent execution environment.\n","operationId":"getTranscriptUploadTarget","tags":["harness-support"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUploadTargetRequest"}}}},"responses":{"200":{"description":"Presigned upload target for the transcript","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadTarget"}}}},"400":{"description":"Invalid request or conversation format does not support transcript uploads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No permission to modify the conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Conversation or transcript slot not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Prepare upload of a block snapshot
> Allocates and returns a storage slot for uploading an output snapshot.\
> The caller should make an HTTP request to the target with the serialized snapshot\
> as the request body.\
> \
> This may only be called from within a cloud agent execution environment.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"harness-support","description":"Internal operations for agent harnesses managed by Oz"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"GetUploadTargetRequest":{"type":"object","description":"Request body for obtaining a conversation-scoped upload target.","required":["conversation_id"],"properties":{"conversation_id":{"type":"string","description":"The conversation ID to associate the uploaded data with."}}},"UploadTarget":{"type":"object","description":"A description of where and how to upload a blob.\nUse the `method` and `url` to upload, including all `headers` in the request.\nPass the blob to upload as the request body.\n","required":["url","method","headers"],"properties":{"url":{"type":"string","format":"uri","description":"The presigned URL to upload the blob to."},"method":{"type":"string","enum":["PUT","POST"],"description":"The HTTP method to use for the upload."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"HTTP headers that must be included in the upload request."}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/harness-support/block-snapshot":{"post":{"summary":"Prepare upload of a block snapshot","description":"Allocates and returns a storage slot for uploading an output snapshot.\nThe caller should make an HTTP request to the target with the serialized snapshot\nas the request body.\n\nThis may only be called from within a cloud agent execution environment.\n","operationId":"getBlockSnapshotUploadTarget","tags":["harness-support"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUploadTargetRequest"}}}},"responses":{"200":{"description":"Presigned upload target for the block snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadTarget"}}}},"400":{"description":"Invalid request or conversation format does not support block snapshot uploads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No permission to modify the conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Conversation or block snapshot slot not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```