> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-retrieving-artifacts.md).

# Retrieving and using artifacts

Learn how to fetch structured output from completed content jobs — outline, draft, SEO metadata, entities, FAQs, FAQ schema, and content score — and how to use each piece in your publishing workflow.

After a content job reaches the `completed` status (or `brief_ready` in stepped mode), you can retrieve its structured artifacts. Each artifact is a self-contained piece of content you can feed directly into your CMS, page template, or downstream automation.

## Endpoint

```
GET /api/agent/v1/copywriter/jobs/:id/artifacts
Authorization: Bearer rk_live_...
```

Replace `:id` with the `job_id` returned when you created the job.

### When to call

* **Auto mode** — Call after the status endpoint returns `"completed"`.
* **Stepped mode at `brief_ready`** — You can call immediately to inspect partial artifacts (outline, SEO metadata, entities, FAQs). The `draft` and `score` fields will be `null` until you approve the brief and the draft finishes generating.
* **Stepped mode after approval** — Poll the status endpoint until `"completed"`, then call artifacts for the full set.

If you call the endpoint before the job is ready, the API returns `409` with the code `not_ready`.

### Scope required

`copywriter:read`

## Full response example

A completed job returns the following JSON structure:

```
{
  "outline": [
    {
      "heading": "What Is Emergency Plumbing?",
      "level": "h2",
      "subheadings": [
        { "heading": "Signs You Need Emergency Service", "level": "h3" }
      ]
    }
  ],
  "draft": {
    "format": "markdown",
    "content": "# Emergency Plumber St. Louis\n\nWhen a pipe bursts...",
    "word_count": 1247
  },
  "seo": {
    "title_tag": "Emergency Plumber St. Louis | 24/7 Licensed Service",
    "meta_description": "Need an emergency plumber in St. Louis? ...",
    "h1": "Emergency Plumber St. Louis"
  },
  "entities": [
    { "name": "St. Louis", "type": "location", "relevance": 0.95 }
  ],
  "faqs": [
    {
      "question": "How much does an emergency plumber cost in St. Louis?",
      "answer": "Emergency plumbing in St. Louis typically costs..."
    }
  ],
  "faq_schema_json_ld": "{\"@context\":\"https://schema.org\",\"@type\":\"FAQPage\",...}",
  "score": {
    "overall": 82,
    "categories": {
      "keyword_coverage": 85,
      "strategic_placement": 78
    }
  }
}
```

## Artifact reference

Each field in the response serves a specific purpose. Below is a detailed breakdown.

### outline

An ordered array of heading objects representing the article structure.

| Field         | Type   | Description                                                |
| ------------- | ------ | ---------------------------------------------------------- |
| `heading`     | string | The heading text                                           |
| `level`       | string | HTML heading level: `h2`, `h3`, or `h4`                    |
| `subheadings` | array  | Nested headings under this section (same shape, recursive) |

**How to use:** Compare the outline against your content strategy before approval (stepped mode). You can also use it to generate a table of contents or validate that the draft covers every planned section.

### draft

The generated article content.

| Field        | Type    | Description                         |
| ------------ | ------- | ----------------------------------- |
| `format`     | string  | Always `"markdown"`                 |
| `content`    | string  | The full article in Markdown format |
| `word_count` | integer | Total word count of the draft       |

**How to use:** Convert the Markdown to HTML for your CMS, or pass it directly to a headless CMS that accepts Markdown. The content is ready to publish but you may want to add your own images, internal links, or brand-specific formatting.

**Stepped mode note:** This field is `null` at `brief_ready`. It populates after the brief is approved and the draft finishes generating.

### seo

Pre-written SEO metadata for the page.

| Field              | Type   | Description                                               |
| ------------------ | ------ | --------------------------------------------------------- |
| `title_tag`        | string | Suggested `<title>` tag (typically 50–60 characters)      |
| `meta_description` | string | Suggested meta description (typically 150–160 characters) |
| `h1`               | string | Suggested H1 heading for the page                         |

**How to use:**

* Set `title_tag` as your page’s `<title>` element.
* Set `meta_description` as the `<meta name="description" content="...">` tag.
* Use `h1` as the visible page heading. This may differ slightly from the title tag for better on-page optimization.

### entities

Named entities extracted during research, ranked by relevance to the topic.

| Field       | Type   | Description                                                        |
| ----------- | ------ | ------------------------------------------------------------------ |
| `name`      | string | The entity name (e.g., "St. Louis", "PVC pipe")                    |
| `type`      | string | Entity category (e.g., `location`, `material`, `brand`, `concept`) |
| `relevance` | number | Relevance score from 0 to 1                                        |

**How to use:** Entities help you understand topical coverage. High-relevance entities that are missing from your draft may represent gaps. You can also use entities for internal linking, tagging, or building topic clusters.

### faqs

Question-and-answer pairs derived from competitor content and People Also Ask data.

| Field      | Type   | Description                                 |
| ---------- | ------ | ------------------------------------------- |
| `question` | string | A frequently asked question about the topic |
| `answer`   | string | A concise answer to the question            |

**How to use:** Add these as an FAQ section at the bottom of your article, or weave individual Q\&A pairs into relevant sections of the content. FAQs improve the chance of appearing in Google’s featured snippets and People Also Ask boxes.

### faq\_schema\_json\_ld

A ready-to-use JSON-LD string for the [FAQPage](https://schema.org/FAQPage) structured data type.

**How to use:** Inject this string into your page’s `<head>` inside a `<script type="application/ld+json">` tag:

```
<script type="application/ld+json">
  {{ faq_schema_json_ld }}
</script>
```

This tells search engines that your page contains FAQ content, which can trigger rich results in the SERP. The schema is pre-built from the `faqs` array — you do not need to construct it yourself.

### score

The content optimization score, calculated by comparing your draft against top-ranking competitors.

| Field        | Type    | Description                                                                     |
| ------------ | ------- | ------------------------------------------------------------------------------- |
| `overall`    | integer | Composite score from 0 to 100                                                   |
| `categories` | object  | Breakdown by scoring category (e.g., `keyword_coverage`, `strategic_placement`) |

**How to use:** Use the overall score as a quality gate in your automation. For example, only publish drafts that score 70 or above, and flag lower-scoring drafts for manual review. The category breakdown tells you exactly where the draft is strong or weak.

**Stepped mode note:** This field is `null` at `brief_ready`. The score is only available after the draft is generated.

## Stepped mode: partial artifacts

In stepped mode, calling the artifacts endpoint at `brief_ready` returns a partial response. This lets you inspect the research output before committing to draft generation.

| Field                | At brief\_ready | At completed |
| -------------------- | --------------- | ------------ |
| `outline`            | Available       | Available    |
| `draft`              | `null`          | Available    |
| `seo`                | Available       | Available    |
| `entities`           | Available       | Available    |
| `faqs`               | Available       | Available    |
| `faq_schema_json_ld` | Available       | Available    |
| `score`              | `null`          | Available    |

To move from `brief_ready` to `completed`, approve the brief:

```
POST /api/agent/v1/copywriter/jobs/:id/approve
Authorization: Bearer rk_live_...
```

Then poll the status endpoint until `"completed"` and fetch artifacts again for the full set.

## Practical examples

### Publishing to a CMS

After retrieving artifacts, map each field to your CMS:

* `seo.title_tag` → Page title / `<title>`
* `seo.meta_description` → Meta description field
* `seo.h1` → Page heading
* `draft.content` → Post body (convert Markdown to HTML if needed)
* `faq_schema_json_ld` → Custom code / head injection field

### Quality gate automation

```
artifacts = fetch_artifacts(job_id)

if artifacts["score"]["overall"] >= 70:
    publish_to_cms(artifacts)
else:
    flag_for_review(job_id, artifacts["score"])
```

### Building a table of contents

```
for section in artifacts["outline"]:
    print(f"{section['level']}: {section['heading']}")
    for sub in section.get("subheadings", []):
        print(f"  {sub['level']}: {sub['heading']}")
```

## Error responses

| HTTP | Code        | When                                                          |
| ---- | ----------- | ------------------------------------------------------------- |
| 404  | `not_found` | Job ID does not exist or does not belong to your organization |
| 409  | `not_ready` | Job has not completed yet — keep polling the status endpoint  |

## Related articles

* [Creating content jobs](/api/api-creating-content-jobs.md) — How to create jobs and understand auto vs stepped mode.
* [Getting started with the API](/api/api-getting-started.md) — End-to-end walkthrough from API key to finished content.
* [Understanding your content score](/copywriter/understanding-your-content-score.md) — How the 0–100 content score is calculated and what each category measures.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.rankability.com/api/api-retrieving-artifacts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.